Utility

create_alias()

This method alters an alias of a collection to another.

Invocation

alter_alias(collection_name, alias, timeout=None, using='default')

Parameters

ParameterDescriptionTypeRequired
collection_nameName of the collection to alter alias toStringTrue
aliasAlias to alterStringTrue
timeoutAn optional duration of time in seconds to allow for the RPC. If it is set to None, the client keeps waiting until the server responds or error occurs.FloatFalse
usingMilvus Connection used to check the segmentsStringFalse

Return

No return.

Raises

  • CollectionNotExistException: error if the collection does not exist.
  • BaseException: error if failed to alter the alias.

bulk_load()

This method load a data file into Milvus.

Invocation

bulk_load(collection_name,is_row_based,files)

Parameters

ParameterDescriptionTypeRequired
collection_nameName of the collection to load data inStringTrue
is_row_basedBoolean value to indicate if the file is row-based.BooleanTrue
filesList of file names to load into Milvus.List[String]True
partition_nameName of the partition to insert data intoStringFalse

Return

No return.

Raises

Example

from pymilvus import utility
tasks = utility.bulk_load(
    collection_name="book",
    is_row_based=True,
    files=["row_based_1.json", "row_based_2.json"]
)

calc_distance()

This method calculate distance between vectors.

Invocation

calc_distance(vectors_left, vectors_right, params=None, timeout=None, using='default')

Parameters

ParameterDescriptionTypeRequired
vectors_leftVectors on the left to the operatorDictTrue
vectors_rightVectors on the right to the operatorDictTrue
paramsParameters used for calculation. Key-value pair parameters: Key: "metric_type"/"metric"; Value: "L2"/"IP"/"HAMMING"/"TANIMOTO", default is "L2". Key: "sqrt"; Value: true or false, default is false - only for "L2" distance. Key: "dim"; Value: Integer - set this value if dimension is not a multiple of 8, otherwise the dimension will be calculated by list length - only for "HAMMING" and "TANIMOTO".DictTrue
timeoutAn optional duration of time in seconds to allow for the RPC. If it is set to None, the client keeps waiting until the server responds or error occurs.FloatFalse
usingMilvus Connection used to drop the collectionStringFalse

Vector example

{"ids": [1, 2, 3, .... n], "collection": "c_1", "partition": "p_1", "field": "v_1"}
{"float_vectors": [[1.0, 2.0], [3.0, 4.0], ... [9.0, 10.0]]} or {"bin_vectors": [b'”', b'N', ... b'Ê']}

Params example

{"metric_type": "L2", "sqrt": true}
{"metric_type": "IP"}
{"metric_type": "HAMMING", "dim": 17}
{"metric_type": "TANIMOTO"}

Return

A two-dimensional array indicates the distances.

Example

vectors_left = {
    "ids": [0, 1], 
    "collection": "book", 
    "partition": "_default", 
    "field": "book_intro"
}
import random
external_vectors = [[random.random() for _ in range(2)] for _ in range(4)]
vectors_right = {"float_vectors": external_vectors}
params = {
    "metric": "IP", 
    "dim": 2
}
from pymilvus import Collection
collection = Collection("book")      # Get an existing collection.
collection.load()
from pymilvus import utility
results = utility.calc_distance(
    vectors_left=vectors_left, 
    vectors_right=vectors_right, 
    params=params
)
print(results)

create_alias()

This method specifies an alias for a collection. Alias cannot be duplicated. Same alias cannot be assigned to different collections. Instead, you can specify multiple aliases for each collection.

Invocation

create_alias(collection_name, alias, timeout=None, using='default')

Parameters

ParameterDescriptionTypeRequired
collection_nameName of the collection to create aliasStringTrue
aliasAlias to createStringTrue
timeoutAn optional duration of time in seconds to allow for the RPC. If it is set to None, the client keeps waiting until the server responds or error occurs.FloatFalse
usingMilvus Connection used to check the segmentsStringFalse

Return

No return.

Raises

  • CollectionNotExistException: error if the collection does not exist.
  • BaseException: error if failed to create the alias.

create_credential()

This method creates an authenticated user access.

Invocation

create_credential(user, password, using='default') 

Parameters

ParameterDescription
userUsername to create.
passwordPassword for the user to create.
usingAlias of the Milvus server to create the user.

Return

No return.

Raises

Example

from pymilvus import utility
utility.create_credential('user', 'password', using='default') 

Note

To stop using the authenticated access, or to log in to another authenticated user, you need to disconnect from the Milvus instance and re-connect to it.

Limitation

  1. Username must not be empty, and must not exceed 32 characters in length. It must start with a letter, and only contains underscores, letters, or numbers.
  2. Password must have at least 6 characters and must not exceed 256 characters in length.

delete_credential()

This method deletes an authenticated user access.

Invocation

delete_credential(user, using='default')

Parameters

ParameterDescription
userUsername to delete.
usingAlias of the Milvus server to delete the user.

Return

No return.

Raises

Example

from pymilvus import utility
users = utility.list_cred_users(using='default')

drop_alias()

This method alters an alias of a collection to another.

Invocation

drop_alias(alias, timeout=None, using='default')

Parameters

ParameterDescriptionTypeRequired
aliasAlias to dropStringTrue
timeoutAn optional duration of time in seconds to allow for the RPC. If it is set to None, the client keeps waiting until the server responds or error occurs.FloatFalse
usingMilvus Connection used to check the segmentsStringFalse

Return

No return.

Raises

  • CollectionNotExistException: error if the collection does not exist.
  • BaseException: error if the alias does not exist.

has_collection()

This method drops a collection and the data within.

Invocation

drop_collection(collection_name, timeout=None, using='default')

Parameters

ParameterDescriptionTypeRequired
collection_nameName of the collection to dropStringTrue
timeoutAn optional duration of time in seconds to allow for the RPC. If it is set to None, the client keeps waiting until the server responds or error occurs.FloatFalse
usingMilvus Connection used to drop the collectionStringFalse

Return

No return.

Example

from pymilvus import utility
utility.drop_collection("book")

get_query_segment_info()

This method checks the information of the segments in the query nodes.

Invocation

get_query_segment_info(collection_name, timeout=None, using='default')

Parameters

ParameterDescriptionTypeRequired
collection_nameName of the collection to checkStringTrue
timeoutAn optional duration of time in seconds to allow for the RPC. If it is set to None, the client keeps waiting until the server responds or error occurs.FloatFalse
usingMilvus Connection used to check the segmentsStringFalse

Return

QuerySegmentInfo.

has_collection()

This method checks if a collection exists.

Invocation

has_collection(collection_name, using='default')

Parameters

ParameterDescriptionTypeRequired
collection_nameName of the collection to checkStringTrue
usingMilvus Connection used to check the collectionStringFalse

Return

Boolean value that indicates if the collection exists.

has_partition()

This method checks if a partition exists in a specified collection.

Invocation

has_partition(collection_name, partition_name, using='default')

Parameters

ParameterDescriptionTypeRequired
collection_nameName of the collection to check the partitionStringTrue
partition_nameName of the partition to checkStringTrue
usingMilvus Connection used to check the collectionStringFalse

Return

Boolean value that indicates if the partition exists.

hybridts_to_datetime()

This method converts a hybrid timestamp to datetime according to timezone.

Invocation

hybridts_to_datetime(hybridts, tz=None)

Parameters

ParameterDescriptionTypeRequired
hybridtsHybrid timestampIntegerTrue
tzTimezone defined by a fixed offset from UTC. If argument tz is set None or not specified, the hybrid timestamp is converted to the local date and time of the platform.datetime.timezoneTrue

Return

The datetime object.

Raises

Exception: error if tz is not of type datetime.timezone.

hybridts_to_unixtime()

This method converts a hybrid timestamp to UNIX Epoch time.

Invocation

hybridts_to_unixtime(hybridts)

Parameters

ParameterDescriptionTypeRequired
hybridtsHybrid timestampIntegerTrue

Return

UNIX Epoch time.

index_building_progress()

This method shows the index building progress.

Invocation

index_building_progress(collection_name, index_name='', using='default')

Parameters

ParameterDescriptionTypeRequired
collection_nameName of the collection to build indexStringTrue
index_nameName of the index to build. Default index will be checked if it is left blank.StringFalse
usingMilvus Connection used to build the indexStringFalse

Return

A dict type contains the number of the indexed entities and the total entity number.

Raises

  • CollectionNotExistException: error if the collection does not exist.
  • IndexNotExistException: error if the index does not exist.

list_collections()

This method lists all collections in Milvus.

Invocation

list_collections(timeout=None, using='default')

Parameters

ParameterDescriptionTypeRequired
timeoutAn optional duration of time in seconds to allow for the RPC. If it is set to None, the client keeps waiting until the server responds or error occurs.FloatFalse
usingMilvus Connection used to check the collectionStringFalse

Return

A list of collection names.

list_cred_users()

This method lists all authenticated user access.

Invocation

list_cred_users(using='default')

Parameters

ParameterDescription
usingAlias of the Milvus server to list users in.

Return

Lists of all authenticated user access.

Raises

Example

from pymilvus import utility
users = utility.list_cred_users(using='default')

Limitation

Password must have at least 6 characters and must not exceed 256 characters in length.

loading_progress()

This method shows the loading progress of sealed segments (in percentage).

Invocation

loading_progress(collection_name, partition_names=None, using='default')

Parameters

ParameterDescriptionTypeRequired
collection_nameName of the collection to loadStringTrue
partition_namesName of the partition(s) to loadlist[String]False
usingMilvus Connection used to load the collectionStringFalse

Return

The loading progress (in percentage).

Raises

PartitionNotExistException: error if the partition does not exist.

mkts_from_datetime()

This method generates a hybrid timestamp based on datetime, timedelta and incremental time interval.

Invocation

mkts_from_datetime(d_time, milliseconds=0.0, delta=None)

Parameters

ParameterDescriptionTypeRequired
d_timeDatetimedatetime.datetimeTrue
millisecondsIncremental time interval. Unit: millisecondsFloatFalse
deltaA duration indicates the difference between two pieces of date, time, or datetime instances to microsecond resolutiondatetime.timedeltaFalse

Return

A new hybrid timestamp.

mkts_from_hybridts()

This method generates a hybrid timestamp based on an existing hybrid timestamp, timedelta and incremental time interval.

Invocation

mkts_from_hybridts(hybridts, milliseconds=0.0, delta=None)

Parameters

ParameterDescriptionTypeRequired
hybridtsThe original hybrid timestampNon-negative integer range from 0 to 18446744073709551615True
millisecondsIncremental time interval. Unit: millisecondsFloatFalse
deltaA duration indicates the difference between two pieces of date, time, or datetime instances to microsecond resolutiondatetime.timedeltaFalse

Return

A new hybrid timestamp.

mkts_from_unixtime()

This method generates a hybrid timestamp based on Unix Epoch time, timedelta and incremental time interval.

Invocation

mkts_from_unixtime(epoch, milliseconds=0.0, delta=None)

Parameters

ParameterDescriptionTypeRequired
epochUnix Epoch timeIntegerTrue
millisecondsIncremental time interval. Unit: millisecondsFloatFalse
deltaA duration indicates the difference between two pieces of date, time, or datetime instances to microsecond resolutiondatetime.timedeltaFalse

Return

A new hybrid timestamp.

reset_password()

This method resets the password of the authenticated user access.

Invocation

reset_password(user, password, using='default')

Parameters

ParameterDescription
userUsername to reset password.
passwordNew password for the username to create.
usingAlias of the Milvus server to reset password in.

Return

No return.

Raises

Example

from pymilvus import utility
utility.reset_password('user', 'new_password', using='default')

Limitation

Password must have at least 6 characters and must not exceed 256 characters in length.

wait_for_index_building_complete()

This method blocks all other operations until index building is done, exception is raised, or timeout is triggered.

Invocation

wait_for_index_building_complete(collection_name, index_name='', timeout=None, using='default')

Parameters

ParameterDescriptionTypeRequired
collection_nameName of the collection to loadStringTrue
index_nameName of the index to build. Default index will be checked if it is left blank.StringFalse
timeoutAn optional duration of time in seconds to allow for the RPC. If it is set to None, the client keeps waiting until the server responds or error occurs.FloatFalse
usingMilvus Connection used to load the collectionStringFalse

Return

No return.

Raises

  • CollectionNotExistException: error if the collection does not exist.
  • IndexNotExistException: error if the index does not exist.

wait_for_loading_complete()

This method blocks all other operations until loading is done, exception is raised, or timeout is triggered.

Invocation

wait_for_loading_complete(collection_name, partition_names=None, timeout=None, using='default')

Parameters

ParameterDescriptionTypeRequired
collection_nameName of the collection to loadStringTrue
partition_namesName of the partition(s) to loadlist[String]False
timeoutAn optional duration of time in seconds to allow for the RPC. If it is set to None, the client keeps waiting until the server responds or error occurs.FloatFalse
usingMilvus Connection used to load the collectionStringFalse

Return

No return.

Raises

  • CollectionNotExistException: error if the collection does not exist.
  • PartitionNotExistException: error if the partition does not exist.