Utility

create_alias()

This method alters an alias of a collection to another.

Invocation

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

Parameters

Parameter	Description	Type	Required
collection_name	Name of the collection to alter alias to	String	True
alias	Alias to alter	String	True
timeout	An 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.	Float	False
using	Milvus Connection used to check the segments	String	False

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

Parameter	Description	Type	Required
collection_name	Name of the collection to load data in	String	True
is_row_based	Boolean value to indicate if the file is row-based.	Boolean	True
files	List of file names to load into Milvus.	List[String]	True
partition_name	Name of the partition to insert data into	String	False

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

Parameter	Description	Type	Required
vectors_left	Vectors on the left to the operator	Dict	True
vectors_right	Vectors on the right to the operator	Dict	True
params	Parameters 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".	Dict	True
timeout	An 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.	Float	False
using	Milvus Connection used to drop the collection	String	False

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

Parameter	Description	Type	Required
collection_name	Name of the collection to create alias	String	True
alias	Alias to create	String	True
timeout	An 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.	Float	False
using	Milvus Connection used to check the segments	String	False

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

Parameter	Description
user	Username to create.
password	Password for the user to create.
using	Alias 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

Parameter	Description
user	Username to delete.
using	Alias 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

Parameter	Description	Type	Required
alias	Alias to drop	String	True
timeout	An 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.	Float	False
using	Milvus Connection used to check the segments	String	False

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

Parameter	Description	Type	Required
collection_name	Name of the collection to drop	String	True
timeout	An 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.	Float	False
using	Milvus Connection used to drop the collection	String	False

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

Parameter	Description	Type	Required
collection_name	Name of the collection to check	String	True
timeout	An 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.	Float	False
using	Milvus Connection used to check the segments	String	False

Return

QuerySegmentInfo.

has_collection()

This method checks if a collection exists.

Invocation

has_collection(collection_name, using='default')

Parameters

Parameter	Description	Type	Required
collection_name	Name of the collection to check	String	True
using	Milvus Connection used to check the collection	String	False

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

Parameter	Description	Type	Required
collection_name	Name of the collection to check the partition	String	True
partition_name	Name of the partition to check	String	True
using	Milvus Connection used to check the collection	String	False

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

Parameter	Description	Type	Required
hybridts	Hybrid timestamp	Integer	True
tz	Timezone 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.timezone	True

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

Parameter	Description	Type	Required
hybridts	Hybrid timestamp	Integer	True

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

Parameter	Description	Type	Required
collection_name	Name of the collection to build index	String	True
index_name	Name of the index to build. Default index will be checked if it is left blank.	String	False
using	Milvus Connection used to build the index	String	False

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

Parameter	Description	Type	Required
timeout	An 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.	Float	False
using	Milvus Connection used to check the collection	String	False

Return

A list of collection names.

list_cred_users()

This method lists all authenticated user access.

Invocation

list_cred_users(using='default')

Parameters

Parameter	Description
using	Alias 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

Parameter	Description	Type	Required
collection_name	Name of the collection to load	String	True
partition_names	Name of the partition(s) to load	list[String]	False
using	Milvus Connection used to load the collection	String	False

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

Parameter	Description	Type	Required
d_time	Datetime	datetime.datetime	True
milliseconds	Incremental time interval. Unit: milliseconds	Float	False
delta	A duration indicates the difference between two pieces of date, time, or datetime instances to microsecond resolution	datetime.timedelta	False

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

Parameter	Description	Type	Required
hybridts	The original hybrid timestamp	Non-negative integer range from 0 to 18446744073709551615	True
milliseconds	Incremental time interval. Unit: milliseconds	Float	False
delta	A duration indicates the difference between two pieces of date, time, or datetime instances to microsecond resolution	datetime.timedelta	False

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

Parameter	Description	Type	Required
epoch	Unix Epoch time	Integer	True
milliseconds	Incremental time interval. Unit: milliseconds	Float	False
delta	A duration indicates the difference between two pieces of date, time, or datetime instances to microsecond resolution	datetime.timedelta	False

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

Parameter	Description
user	Username to reset password.
password	New password for the username to create.
using	Alias 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

Parameter	Description	Type	Required
collection_name	Name of the collection to load	String	True
index_name	Name of the index to build. Default index will be checked if it is left blank.	String	False
timeout	An 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.	Float	False
using	Milvus Connection used to load the collection	String	False

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

Parameter	Description	Type	Required
collection_name	Name of the collection to load	String	True
partition_names	Name of the partition(s) to load	list[String]	False
timeout	An 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.	Float	False
using	Milvus Connection used to load the collection	String	False

Return

No return.

Raises

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