Collection()

This is the constructor method to create a collection with the specified schema or to get an existing collection with the name.

Invocation

Collection(name, schema=None, using='default', shards_num=2, **kwargs)

Parameters

Parameter	Description	Type	Required
`name`	Name of the collection	String	True
`schema`	Schema of the collection to create	class schema.CollectionSchema	False
`using`	Milvus Connection used to create the collection	String	False
`shards_num`	Shard number of the collection to create. It corresponds to the number of data nodes used to insert data.	INT32	False
`kwargs` consistency_level	With which consistency level to create the collection	String/Integer	False

A schema specifies the properties of a collection and the fields within. See Schema for more information.

Return

A new collection object created with the specified schema or an existing collection object by name.

Properties

Property	Description	Type
`name`	Name of the collection	String
`schema`	Schema of the collection	class schema.CollectionSchema
`description`	Description of the collection	String
`is_empty`	Boolean value to indicate if the collection is empty	Bool
`num_entities`	Number of entities in the collection	Integer
`primary_field`	Schema of the primary field in the collection	class schema.FieldSchema
`partitions`	List of all partitions in the collection	list[String]
`indexes`	List of all indexes in the collection	list[String]

Raises

CollectionNotExistException: error if the collection does not exist.

Example

from pymilvus import CollectionSchema, FieldSchema, DataType, Collection
book_id = FieldSchema(
  name="book_id", 
  dtype=DataType.INT64, 
  is_primary=True, 
)
word_count = FieldSchema(
  name="word_count", 
  dtype=DataType.INT64,  
)
book_intro = FieldSchema(
  name="book_intro", 
  dtype=DataType.FLOAT_VECTOR, 
  dim=2
)
schema = CollectionSchema(
  fields=[book_id, word_count, book_intro], 
  description="Test book search"
)
collection_name = "book"
collection = Collection(
    name=collection_name, 
    schema=schema, 
    using='default', 
    shards_num=2,
    consistency_level="Strong"
)
collection.schema
{
  auto_id: False
  description: Test book search
  fields: [{
    name: book_id
    description: 
    type: 5
    is_primary: True
    auto_id: False
  }, {
    name: word_count
    description: 
    type: 5
  }, {
    name: book_intro
    description: 
    type: 101
    params: {'dim': 2}
  }]
}
collection.description
'Test book search'
collection.name
'book'
collection.is_empty
True
collection.primary_field
{
    name: book_id
    description: 
    type: 5
    is_primary: True
    auto_id: False
  }

create_index()

This method creates an index with the specified index parameter.

Invocation

create_index(field_name, index_params, timeout=None, **kwargs)

Parameters

Parameter	Description	Type	Required
`field_name`	Name of the field to create index on	String	True
`index_params`	Parameters of the index to create	Dict	True
`index_name`	Name of the index to create	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

Return

The newly created index object.

Raises

CollectionNotExistException: error if the collection does not exist.
ParamError: error if the parameters are invalid.
BaseException: error if the specified field does not exist.
BaseException: error if the index has been created.

Example

index_params = {
  "metric_type":"L2",
  "index_type":"IVF_FLAT",
  "params":{"nlist":1024}
}
from pymilvus import Collection
collection = Collection("book")      # Get an existing collection.
collection.create_index(
  field_name="book_intro", 
  index_params=index_params
)

Note

The index_names of different indexes in the same collection must be different, so there can be at most one index whose name is _default_idx_ in a collection.
Using the same field_name, index_params, index_name to create the same index repeatedly will return success directly.
Indexes can be built for scalar fields. In this case, index_params can be omitted. Milvus will then build default dictionary tree indexes for fields of type VARCHAR, and sort fields data of other data types in ascending order.

create_partition()

This method creates a partition with the specified name.

Invocation

create_partition(partition_name, description="")

Parameters

Parameter	Description	Type	Required
`partition_name`	Name of the partition to create	String	True
`description`	Description of the partition to create	String	False

Return

The newly created partition object.

Raises

CollectionNotExistException: error if the collection does not exist.
BaseException: error if the specified partition does not exist.

Example

from pymilvus import Collection
collection = Collection("book")      # Get an existing collection.
collection.create_partition("novel")

delete()

This method deletes entities from a specified collection.

Invocation

delete(expr, partition_name=None, timeout=None, **kwargs)

Parameters

Parameter	Description	Type	Required
`expr`	Boolean expression that specifies the primary keys of the entities to delete	String	True
`partition_name`	Name of the partition to delete data from	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

Return

A MutationResult object.

Properties

Property	Description	Type
`delete_count`	Number of the entities to delete	Integer

Raises

RpcError: error if gRPC encounter an error.
ParamError: error if the parameters are invalid.
BaseException: error if the return result from server is not ok.

Example

expr = "book_id in [0,1]"
from pymilvus import Collection
collection = Collection("book")      # Get an existing collection.
collection.delete(expr)

drop_index()

This method drops the index and its corresponding index file in the collection.

Invocation

drop_index(timeout=None, **kwargs)

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

Return

No return.

Raises

CollectionNotExistException: error if the collection does not exist.
BaseException: error if the index does not exist.

Example

from pymilvus import Collection
collection = Collection("book")      # Get an existing collection.
collection.drop_index()

drop_partition()

This method drops a partition and the data within by name in the specified collection.

Invocation

drop_partition(partition_name, timeout=None, **kwargs)

Parameters

Parameter	Description	Type	Required
`partition_name`	Name of the partition 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

Return

No return.

Raises

CollectionNotExistException: error if the collection does not exist.
BaseException: error if the specified partition does not exist.

Example

from pymilvus import Collection
collection = Collection("book")      # Get an existing collection.
collection.drop_partition("novel")

get_replicas()

This method checks the replica information.

Invocation

get_replicas()

Return

The information about replica groups and the corresponding query nodes and shard.

Raises

Example

from pymilvus import Collection
collection = Collection("book")      # Get an existing collection.
collection.load(replica_number=2)    # Load collection as 2 replicas
result = collection.get_replicas()
print(result)

has_index()

This method verifies if a specified index exists.

Invocation

has_index(timeout=None)

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

Return

A boolean value that indicates if the index exists.

Raises

CollectionNotExistException: error if the collection does not exist.

Example

from pymilvus import Collection
collection = Collection("book")      # Get an existing collection.
collection.has_index()

has_partition()

This method verifies if a partition exists in the specified collection.

Invocation

has_partition(partition_name, timeout=None)

Parameters

Parameter	Description	Type	Required
`partition_name`	Name of the partition to verify	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

Return

A boolean value that indicates if the partition exists.

Raises

CollectionNotExistException: error if the collection does not exist.
BaseException: error if the specified partition does not exist.

Example

from pymilvus import Collection
collection = Collection("book")      # Get an existing collection.
collection.has_partition("novel")

index()

This method gets the index object in the collection.

Invocation

index()

Return

The index object.

Raises

CollectionNotExistException: error if the collection does not exist.
BaseException: error if the specified partition does not exist.

Example

from pymilvus import Collection
collection = Collection("book")      # Get an existing collection.
collection.index()

insert()

This method inserts data into a specified collection.

Invocation

insert(data, partition_name=None, timeout=None, **kwargs)

Parameters

Parameter	Description	Type	Required
`data`	Data to insert	list-like(list, tuple)	True
`partition_name`	Name of the partition to insert data into	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

Return

A MutationResult object.

Properties

Property	Description	Type
`insert_count`	Number of the inserted entities	Integer
`primary_keys`	List of the primary keys of the inserted entities	list[String]

Raises

CollectionNotExistException: error if the collection does not exist.
ParamError: error if the parameters are invalid.
BaseException: error if the specified partition does not exist.

Example

import random
data = [
  [i for i in range(2000)],
  [i for i in range(10000, 12000)],
  [[random.random() for _ in range(2)] for _ in range(2000)],
]
from pymilvus import Collection
collection = Collection("book")      # Get an existing collection.
mr = collection.insert(data)

load()

This method loads the specified collection to memory (for search or query).

Invocation

load(partition_names=None, timeout=None, **kwargs)

Parameters

Parameter	Description	Type	Required
`partition_names`	Name of the partition(s) to load	list[String]	False
`replica_number`	Number of the replica(s) to load	Integer	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
`kwargs` _async	Boolean value to indicate if to invoke asynchronously	Bool	False

Return

No return.

Raises

CollectionNotExistException: error if the collection does not exist.
ParamError: error if the parameters are invalid.
BaseException: error if the specified partition does not exist.

Example

from pymilvus import Collection
collection = Collection("book")      # Get an existing collection.
collection.load()

partition()

This method gets the specified partition object.

Invocation

partition(partition_name)

Parameters

Parameter	Description	Type	Required
`partition_name`	Name of the partition to get	String	true

Return

The specified partition object.

Raises

CollectionNotExistException: error if the collection does not exist.
BaseException: error if the specified partition does not exist.

Example

from pymilvus import Collection
collection = Collection("book")      # Get an existing collection.
collection.partition("novel")

query()

This method conducts a vector query.

Invocation

query(expr, output_fields=None, partition_names=None, timeout=None, **kwargs)

Parameters

Parameter	Description	Type	Required
`expr`	Boolean expression to filter the data	String	True
`partition_names`	List of names of the partitions to search on. All partition will be searched if it is left empty.	list[String]	False
`output_fields`	List of names of fields to output	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
`kwargs` consistency_level guarantee_timestamp graceful_time travel_timestamp	Consistency level used in the search Milvus searches on the data view before this timestamp when it is provided. Otherwise, it searches the most updated data view. It can be only used in Customized level of consistency. PyMilvus will use current timestamp minus the graceful_time as the guarantee_timestamp for search. It can be only used in Bounded level of consistency. Timestamp that is used for Time Travel. Users can specify a timestamp in a search to get results based on a data view at a specified point in time.	String/Integer Integer Integer Integer	False

Return

A list that contains all results.

Raises

RpcError: error if gRPC encounter an error.
ParamError: error if the parameters are invalid.
DataTypeNotMatchException: error if wrong type of data is passed to server.
BaseException: error if the return result from server is not ok.

Example

from pymilvus import Collection
collection = Collection("book")      # Get an existing collection.
res = collection.query(
  expr = "book_id in [2,4,6,8]", 
  output_fields = ["book_id", "book_intro"],
  consistency_level="Strong"
)
sorted_res = sorted(res, key=lambda k: k['book_id'])
sorted_res

release()

This method releases the specified collection from memory.

Invocation

release(timeout=None, **kwargs)

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

Return

No return.

Raises

CollectionNotExistException: error if the collection does not exist.
BaseException: error if the collection has not been loaded to memory.

Example

from pymilvus import Collection
collection = Collection("book")      # Get an existing collection.
collection.release()

search()

This method conducts a vector similarity search.

Invocation

search(data, anns_field, param, limit, expr=None, partition_names=None, output_fields=None, timeout=None, round_decimal=-1, **kwargs)

Parameters

Parameter	Description	Type	Required
`data`	Data to search with	list[list[Float]]	True
`anns_field`	Name of the vector field to search on	String	True
`param`	Specific search parameter(s) of the index on the vector field	Dict	True
`limit`	Number of nearest records to return	Integer	True
`expr`	Boolean expression to filter the data	String	False
`partition_names`	List of names of the partitions to search on. All partition will be searched if it is left empty.	list[String]	False
`output_fields`	List of names of fields to output	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
`round_decimal`	Number of the decimal places of the returned distance	Integer	False
`kwargs` _async _callback consistency_level guarantee_timestamp graceful_time travel_timestamp	Boolean value to indicate if to invoke asynchronously Function that will be invoked after server responds successfully. It takes effect only if `_async` is set to `True`. Consistency level used in the search Milvus searches on the data view before this timestamp when it is provided. Otherwise, it searches the most updated data view. It can be only used in Customized level of consistency. PyMilvus will use current timestamp minus the graceful_time as the guarantee_timestamp for search. It can be only used in Bounded level of consistency. Timestamp that is used for Time Travel. Users can specify a timestamp in a search to get results based on a data view at a specified point in time.	Bool Function String/Integer Integer Integer Integer	False

Return

A SearchResult object, an iterable, 2d-array-like class whose first dimension is the number of vectors to query (nq), and the second dimension is the number of limit (topk).

Raises

RpcError: error if gRPC encounter an error.
ParamError: error if the parameters are invalid.
DataTypeNotMatchException: error if wrong type of data is passed to server.
BaseException: error if the return result from server is not ok.

Example

search_params = {"metric_type": "L2", "params": {"nprobe": 10}}
from pymilvus import Collection
collection = Collection("book")      # Get an existing collection.
results = collection.search(
    data=[[0.1, 0.2]], 
    anns_field="book_intro", 
    param=search_params, 
    limit=10, 
    expr=None,
    consistency_level="Strong"
)
results[0].ids
results[0].distances