Collection Operations

Collection APIs manage schemas, collection lifecycle, load/release state, aliases, functions, compaction, external collections, and snapshots.

import {
  CollectionProperties,
  DataType,
  FunctionType,
  IndexType,
  MetricType,
} from '@zilliz/milvus2-sdk-node';

createCollection

Create a collection. MilvusClient#createCollection supports both a quick-create form and explicit schema forms.

createCollection(
  data: CreateColReq | CreateColWithSchemaAndIndexParamsReq | CreateCollectionReq
): Promise<ResStatus>

Quick-create parameters

• collection_name: Collection name.
• dimension: Vector dimension.
• primary_field_name?: Primary key field name. Defaults to id.
• id_type?: DataType.Int64 or DataType.VarChar.
• vector_field_name?: Vector field name. Defaults to embedding.
• metric_type?: Metric type for the default index.
• enable_dynamic_field? / enableDynamicField?: Enable dynamic field. Defaults to true.
• auto_id?: Whether primary key auto-increments.
• consistency_level?: Consistency level.
• index_params?: Optional index params.
• db_name?: Database name.
• timeout?: Request timeout in milliseconds.

Example:

await client.createCollection({
  collection_name: 'books',
  dimension: 768,
  metric_type: 'COSINE',
});

Explicit schema parameters

• collection_name: Collection name.
• fields or schema: Field schema array.
• shards_num?: Number of shards.
• description?: Collection description.
• consistency_level?: Consistency level.
• num_partitions?: Initial partition count.
• partition_key_field?: Partition key field.
• clustering_key_field?: Clustering key field.
• enable_dynamic_field? / enableDynamicField?: Enable dynamic field.
• properties?: Collection properties such as TTL or mmap settings.
• functions?: Collection functions such as BM25 or text embedding.
• external_source?, external_spec?, do_physical_backfill?, file_resource_ids?: External collection configuration.
• db_name?: Database name.
• timeout?: Request timeout in milliseconds.

Example:

await client.createCollection({
  collection_name: 'books',
  fields: [
    { name: 'id', data_type: DataType.Int64, is_primary_key: true },
    { name: 'title', data_type: DataType.VarChar, max_length: 512 },
    { name: 'embedding', data_type: DataType.FloatVector, dim: 768 },
  ],
  properties: {
    [CollectionProperties.TTL_SECONDS]: 86_400,
  },
});

Schema mutation

Milvus 3.0

Milvus 3.0 introduces collection schema alteration for adding and dropping fields and for atomically managing function output fields and indexes. The Node SDK exposes these operations through the following field and function methods.

addCollectionField

Add one field to an existing collection.

addCollectionField(data: AddCollectionFieldReq): Promise<ResStatus>

Parameters:

• collection_name: Collection name.
• field: Field schema.
• db_name?: Database name.
• timeout?: Request timeout in milliseconds.

addCollectionFields

Add multiple fields by calling addCollectionField for each field.

addCollectionFields(data: AddCollectionFieldsReq): Promise<ResStatus>

Parameters:

• collection_name: Collection name.
• fields: Field schema array.
• db_name?: Database name.
• timeout?: Request timeout in milliseconds.

dropCollectionField

Drop a field by name or field ID.

dropCollectionField(data: DropCollectionFieldReq): Promise<ResStatus>

Provide exactly one field identifier:

• field_name: Field name.
• field_id: Positive numeric field ID returned by describeCollection.
• collection_name: Collection name.
• db_name?: Database name.
• timeout?: Request timeout in milliseconds.

await client.dropCollectionField({
  collection_name: 'books',
  field_name: 'legacy_category',
});

alterCollectionFieldProperties

Modify field properties, such as max_length or mmap.enabled.

alterCollectionFieldProperties(data: AlterCollectionFieldPropertiesReq): Promise<ResStatus>

Parameters:

• collection_name: Collection name.
• field_name: Field name.
• properties: Properties to set.
• db_name?: Database name.
• timeout?: Request timeout in milliseconds.

Example:

await client.alterCollectionFieldProperties({
  collection_name: 'books',
  field_name: 'title',
  properties: { max_length: 1024 },
});

Collection inspection

hasCollection

Check if a collection exists.

hasCollection(data: HasCollectionReq): Promise<BoolResponse>

Response: value is true when the collection exists.

showCollections

List collections or loaded collections.

showCollections(data?: ShowCollectionsReq): Promise<ShowCollectionsResponse>
listCollections(data?: ShowCollectionsReq): Promise<ShowCollectionsResponse> // alias
list_collections(data?: ShowCollectionsReq): Promise<ShowCollectionsResponse> // alias

Parameters:

• type?: ShowCollectionsType.All or ShowCollectionsType.Loaded.
• collection_names?: Collection names to check when using loaded status.
• db_name?: Database name.
• timeout?: Request timeout in milliseconds.

Response:

• data[]: Collection info with name, id, timestamp, and loadedPercentage.

describeCollection

Describe schema and collection metadata.

describeCollection(data: DescribeCollectionReq): Promise<DescribeCollectionResponse>

Parameters:

• collection_name: Collection name.
• cache?: Return cached schema when true.
• db_name?: Database name.
• timeout?: Request timeout in milliseconds.

Response highlights:

• schema.fields: Field schema list.
• schema.functions: Function schemas.
• collectionID, collection_name, consistency_level.
• aliases.
• properties.
• anns_fields, scalar_fields, function_fields: SDK-formatted field maps.

batchDescribeCollections

Describe multiple collections in one request.

batchDescribeCollections(data: BatchDescribeCollectionReq): Promise<BatchDescribeCollectionResponse>

Parameters:

• collection_names: Collection names.
• collectionIDs?: Collection IDs.
• db_name?: Database name.
• timeout?: Request timeout in milliseconds.

getCollectionStatistics

Get collection statistics.

getCollectionStatistics(data: GetCollectionStatisticsReq): Promise<StatisticsResponse>
getCollectionStats(data: GetCollectionStatisticsReq): Promise<StatisticsResponse> // alias

Response:

• stats: Raw key-value statistics.
• data.row_count: Parsed row count.

Collection properties

alterCollectionProperties

Modify collection properties.

alterCollectionProperties(data: AlterCollectionReq): Promise<ResStatus>
alterCollection(data: AlterCollectionReq): Promise<ResStatus> // deprecated alias

Parameters:

• collection_name: Collection name.
• properties: Properties to set.
• delete_keys?: Property keys to delete.
• db_name?: Database name.
• timeout?: Request timeout in milliseconds.

Example:

await client.alterCollectionProperties({
  collection_name: 'books',
  properties: { [CollectionProperties.MMAP_ENABLED]: true },
});

dropCollectionProperties

Remove collection properties.

dropCollectionProperties(data: DropCollectionPropertiesReq): Promise<ResStatus>

Parameters:

• collection_name: Collection name.
• properties: Property keys to remove.
• db_name?: Database name.
• timeout?: Request timeout in milliseconds.

Load and release

loadCollectionAsync

Start loading a collection without waiting for completion.

loadCollectionAsync(data: LoadCollectionReq): Promise<ResStatus>

loadCollection

Load a collection and wait until loading progress reaches 100%.

loadCollection(data: LoadCollectionReq): Promise<ResStatus>
loadCollectionSync(data: LoadCollectionReq): Promise<ResStatus> // alias

Parameters:

• collection_name: Collection name.
• replica_number?: Replica count.
• resource_groups?: Target resource groups.
• refresh?: Refresh loaded data.
• load_fields?: Fields to load.
• skip_load_dynamic_field?: Skip dynamic field loading.
• db_name?: Database name.
• timeout?: Request timeout in milliseconds.

refreshLoad

Refresh a loaded collection to pick up schema or data changes.

refreshLoad(data: RefreshLoadReq): Promise<ResStatus>

releaseCollection

Release a collection from query nodes.

releaseCollection(data: ReleaseLoadCollectionReq): Promise<ResStatus>

getLoadingProgress

Get load progress for a collection or partitions.

getLoadingProgress(data: GetLoadingProgressReq): Promise<GetLoadingProgressResponse>

getLoadState

Get collection or partition load state.

getLoadState(data: GetLoadStateReq): Promise<GetLoadStateResponse>

Rename, truncate, and drop

renameCollection

Rename a collection and optionally move it to another database.

renameCollection(data: RenameCollectionReq): Promise<ResStatus>

Parameters:

• collection_name: Current collection name.
• new_collection_name: New collection name.
• new_db_name?: Target database name.
• db_name?: Current database name.
• timeout?: Request timeout in milliseconds.

truncateCollection

Delete all rows while keeping the schema.

truncateCollection(data: DropCollectionReq): Promise<{ status: ResStatus }>

dropCollection

Drop a collection and all its data.

dropCollection(data: DropCollectionReq): Promise<ResStatus>
drop_collection(data: DropCollectionReq): Promise<ResStatus> // alias

Alias operations

createAlias

createAlias(data: CreateAliasReq): Promise<ResStatus>

Parameters: collection_name, alias, optional db_name, optional timeout.

describeAlias

describeAlias(data: DescribeAliasReq): Promise<DescribeAliasResponse>

listAliases

listAliases(data: ListAliasesReq): Promise<ListAliasesResponse>

alterAlias

alterAlias(data: AlterAliasReq): Promise<ResStatus>

dropAlias

dropAlias(data: DropAliasReq): Promise<ResStatus>

Function operations

alterCollectionSchema

Low-level schema alteration API for atomically adding a function output field, its function schema, and optional bound index metadata.

alterCollectionSchema(
  data: AlterCollectionSchemaReq
): Promise<AlterCollectionSchemaResponse>

Parameters:

• collection_name: Collection name.
• field: Function output field schema.
• function: Function schema.
• do_physical_backfill?: Backfill existing rows.
• index_name?: Name of the bound index.
• extra_params?: Bound index parameters.
• db_name?: Database name.
• timeout?: Request timeout in milliseconds.

addFunctionField

Convenience wrapper for adding a BM25 or MinHash function output field and its bound index in one schema alteration.

addFunctionField(data: AddFunctionFieldReq): Promise<ResStatus>

The output field must be SparseFloatVector for BM25 and BinaryVector for MinHash. A non-AUTOINDEX index_type is required.

await client.addFunctionField({
  collection_name: 'documents',
  field: {
    name: 'minhash_vector',
    data_type: DataType.BinaryVector,
    dim: 512,
    is_function_output: true,
  },
  function: {
    name: 'body_minhash',
    type: FunctionType.MINHASH,
    input_field_names: ['body'],
    output_field_names: ['minhash_vector'],
    params: { num_hashes: 16, shingle_size: 3 },
  },
  index_name: 'minhash_index',
  extra_params: {
    index_type: IndexType.MINHASH_LSH,
    metric_type: MetricType.MHJACCARD,
    params: { mh_lsh_band: 8 },
  },
});

dropFunctionField

Drop a function together with its output fields and bound indexes.

dropFunctionField(data: DropFunctionFieldReq): Promise<ResStatus>

await client.dropFunctionField({
  collection_name: 'documents',
  function_name: 'body_minhash',
});

addCollectionFunction

Add a function to a collection, such as BM25, text embedding, or rerank. This method is deprecated for schema-evolution workflows; use addFunctionField when the output field and index must be created atomically.

addCollectionFunction(data: AddCollectionFunctionReq): Promise<ResStatus>

Parameters:

• collection_name: Collection name.
• function: Function schema.
• db_name?: Database name.
• timeout?: Request timeout in milliseconds.

Example:

await client.addCollectionFunction({
  collection_name: 'books',
  function: {
    name: 'title_bm25',
    type: FunctionType.BM25,
    input_field_names: ['title'],
    output_field_names: ['title_sparse'],
    params: {},
  },
});

alterCollectionFunction

alterCollectionFunction(data: AlterCollectionFunctionReq): Promise<ResStatus>

dropCollectionFunction

This method is deprecated for schema-evolution workflows. Use dropFunctionField to remove the function output fields and indexes as well.

dropCollectionFunction(data: DropCollectionFunctionReq): Promise<ResStatus>

Compaction and replicas

compact

Trigger compaction.

compact(data: CompactReq): Promise<CompactionResponse>

getCompactionState

getCompactionState(data: GetCompactionStateReq): Promise<GetCompactionStateResponse>

getCompactionStateWithPlans

getCompactionStateWithPlans(data: GetCompactionPlansReq): Promise<GetCompactionPlansResponse>

getReplicas

Get collection replica information.

getReplicas(data: GetReplicaReq): Promise<ReplicasResponse>
describeReplicas(data: GetReplicaReq): Promise<ReplicasResponse> // alias

Primary key helpers

getPkFieldName(data: DescribeCollectionReq, desc?: DescribeCollectionResponse): Promise<string>
getPkFieldType(data: DescribeCollectionReq, desc?: DescribeCollectionResponse): Promise<keyof typeof DataType>
getPkField(data: DescribeCollectionReq): Promise<FieldSchema>

External collection refresh Milvus 3.0

refreshExternalCollection

Trigger a refresh job for an external collection.

refreshExternalCollection(data: RefreshExternalCollectionReq): Promise<RefreshExternalCollectionResponse>

Parameters:

• collection_name: Collection name.
• external_source?: New external source path.
• external_spec?: New external spec configuration.
• db_name?: Database name.
• timeout?: Request timeout in milliseconds.

getRefreshExternalCollectionProgress

getRefreshExternalCollectionProgress(data: GetRefreshExternalCollectionProgressReq): Promise<GetRefreshExternalCollectionProgressResponse>

Parameters: job_id, optional timeout.

listRefreshExternalCollectionJobs

listRefreshExternalCollectionJobs(data?: ListRefreshExternalCollectionJobsReq): Promise<ListRefreshExternalCollectionJobsResponse>

Parameters: optional db_name, collection_name, and timeout.

Snapshots Milvus 3.0

createSnapshot

createSnapshot(data: CreateSnapshotReq): Promise<ResStatus>

Parameters:

• collection_name: Collection name.
• snapshot_name: Snapshot name.
• description?: Snapshot description.
• compaction_protection_seconds?: Protection duration.
• db_name?: Database name.
• timeout?: Request timeout in milliseconds.

dropSnapshot

dropSnapshot(data: DropSnapshotReq): Promise<ResStatus>

listSnapshots

listSnapshots(data: ListSnapshotsReq): Promise<ListSnapshotsResponse>

describeSnapshot

describeSnapshot(data: DescribeSnapshotReq): Promise<DescribeSnapshotResponse>

restoreSnapshot

Restore a snapshot into a target collection.

restoreSnapshot(data: RestoreSnapshotReq): Promise<RestoreSnapshotResponse>

Parameters:

• snapshot_name: Snapshot name.
• source_collection_name: Source collection.
• target_collection_name: Target collection.
• source_db_name?: Source database.
• target_db_name?: Target database.
• timeout?: Request timeout in milliseconds.

getRestoreSnapshotState

getRestoreSnapshotState(data: GetRestoreSnapshotStateReq): Promise<GetRestoreSnapshotStateResponse>

listRestoreSnapshotJobs

listRestoreSnapshotJobs(data?: ListRestoreSnapshotJobsReq): Promise<ListRestoreSnapshotJobsResponse>

pinSnapshotData

Pin snapshot data to protect it from garbage collection while it is copied out.

pinSnapshotData(data: PinSnapshotDataReq): Promise<PinSnapshotDataResponse>

Parameters: collection_name, snapshot_name, optional ttl_seconds, db_name, and timeout.

unpinSnapshotData

Release a snapshot data pin.

unpinSnapshotData(data: UnpinSnapshotDataReq): Promise<ResStatus>

Parameters: pin_id, optional timeout.

Related

• API Reference overview
• Collection Management guide
• Data Operations