# Index Management

Build and tune vector and scalar indexes for Milvus collections, check index status, and drop or rebuild indexes from Node.js.

SDK: `@zilliz/milvus2-sdk-node@3.0.10` · Tested with Milvus 3.0.6

Canonical documentation: https://milvus-io.github.io/milvus-sdk-node/management/index-management/

## Section links

- [Creating Indexes](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#creating-indexes)
- [Basic Index Creation](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#basic-index-creation)
- [Index with Parameters](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#index-with-parameters)
- [Index Types](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#index-types)
- [HNSW (Hierarchical Navigable Small World)](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#hnsw-hierarchical-navigable-small-world)
- [IVF_FLAT (Inverted File Flat)](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#ivf_flat-inverted-file-flat)
- [IVF_SQ8 (Inverted File Scalar Quantization)](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#ivf_sq8-inverted-file-scalar-quantization)
- [IVF_PQ (Inverted File Product Quantization)](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#ivf_pq-inverted-file-product-quantization)
- [FLAT](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#flat)
- [AUTOINDEX](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#autoindex)
- [MINHASH_LSH](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#minhash_lsh)
- [Metric Types](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#metric-types)
- [Index Operations](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#index-operations)
- [Describe Index](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#describe-index)
- [List Indexes](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#list-indexes)
- [Get Index State](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#get-index-state)
- [Get Index Build Progress](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#get-index-build-progress)
- [Alter Index Properties](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#alter-index-properties)
- [Drop Index Properties](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#drop-index-properties)
- [Drop Index](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#drop-index)
- [Index Best Practices](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#index-best-practices)
- [Choosing an Index Type](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#choosing-an-index-type)
- [Index Parameters](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#index-parameters)
- [Metric Type Selection](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#metric-type-selection)
- [Index Building](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#index-building)
- [Complete Example](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#complete-example)
- [Next Steps](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#next-steps)
- [Additional index enums in SDK 3.0.5](https://milvus-io.github.io/milvus-sdk-node/management/index-management/#additional-index-enums-in-sdk-305)

Indexes are crucial for optimizing search performance in Milvus. This guide covers creating, managing, and optimizing indexes.

## Creating Indexes

### Basic Index Creation

Create an index on a vector field:

```javascript
await client.createIndex({
  collection_name: 'my_collection',
  field_name: 'vector',
  index_type: 'HNSW',
  metric_type: 'L2',
});
```

### Index with Parameters

Specify index parameters:

```javascript
await client.createIndex({
  collection_name: 'my_collection',
  field_name: 'vector',
  index_type: 'HNSW',
  metric_type: 'L2',
  params: {
    M: 16,
    efConstruction: 200,
  },
});
```

## Index Types

### HNSW (Hierarchical Navigable Small World)

Best for high-dimensional vectors and high recall:

```javascript
await client.createIndex({
  collection_name: 'my_collection',
  field_name: 'vector',
  index_type: 'HNSW',
  metric_type: 'L2',
  params: {
    M: 16, // Number of connections
    efConstruction: 200, // Construction parameter
  },
});
```

### IVF_FLAT (Inverted File Flat)

Good balance of speed and accuracy:

```javascript
await client.createIndex({
  collection_name: 'my_collection',
  field_name: 'vector',
  index_type: 'IVF_FLAT',
  metric_type: 'L2',
  params: {
    nlist: 1024, // Number of clusters
  },
});
```

### IVF_SQ8 (Inverted File Scalar Quantization)

Memory-efficient version of IVF_FLAT:

```javascript
await client.createIndex({
  collection_name: 'my_collection',
  field_name: 'vector',
  index_type: 'IVF_SQ8',
  metric_type: 'L2',
  params: {
    nlist: 1024,
  },
});
```

### IVF_PQ (Inverted File Product Quantization)

Most memory-efficient, good for large datasets:

```javascript
await client.createIndex({
  collection_name: 'my_collection',
  field_name: 'vector',
  index_type: 'IVF_PQ',
  metric_type: 'L2',
  params: {
    nlist: 1024,
    m: 8, // Number of sub-vectors
    nbits: 8, // Number of bits per sub-vector
  },
});
```

### FLAT

Exact search, no index (for small datasets):

```javascript
await client.createIndex({
  collection_name: 'my_collection',
  field_name: 'vector',
  index_type: 'FLAT',
  metric_type: 'L2',
});
```

### AUTOINDEX

Let Milvus choose the best index:

```javascript
await client.createIndex({
  collection_name: 'my_collection',
  field_name: 'vector',
  index_type: 'AUTOINDEX',
  metric_type: 'L2',
});
```

### MINHASH_LSH

`MINHASH_LSH` is an index for binary vectors that uses MinHash locality-sensitive hashing. It is useful for approximate similarity search on binary signatures, sets, shingles, or other binary encodings where Jaccard-style similarity is appropriate.

```javascript
await client.createCollection({
  collection_name: 'binary_docs',
  fields: [
    { name: 'id', data_type: DataType.Int64, is_primary_key: true },
    { name: 'binary_vector', data_type: DataType.BinaryVector, dim: 128 },
  ],
});

await client.createIndex({
  collection_name: 'binary_docs',
  field_name: 'binary_vector',
  index_type: 'MINHASH_LSH',
  metric_type: 'JACCARD',
});
```

For binary vectors, the `dim` value must be a multiple of 8, and inserted binary vector payloads use `dim / 8` bytes.

Milvus 3.0 can generate MinHash binary signatures from a text field and create the bound index atomically:

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

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 },
  },
});
```

Use `MHJACCARD` for MinHash function output. Plain binary-vector workflows can continue to use `JACCARD` when appropriate.

## Metric Types

Choose the appropriate metric type for your use case:

- **L2**: Euclidean distance (most common)
- **IP**: Inner product
- **COSINE**: Cosine similarity
- **HAMMING**: Hamming distance (for binary vectors)
- **JACCARD**: Jaccard distance (for binary vectors, including MinHash use cases)

```javascript
// L2 distance
await client.createIndex({
  collection_name: 'my_collection',
  field_name: 'vector',
  index_type: 'HNSW',
  metric_type: 'L2',
});

// Cosine similarity
await client.createIndex({
  collection_name: 'my_collection',
  field_name: 'vector',
  index_type: 'HNSW',
  metric_type: 'COSINE',
});
```

## Index Operations

### Describe Index

Get index information:

```javascript
const indexInfo = await client.describeIndex({
  collection_name: 'my_collection',
  field_name: 'vector',
});

for (const index of indexInfo.index_descriptions) {
  const params = Object.fromEntries(
    index.params.map(({ key, value }) => [key, value])
  );
  console.log('Index type:', params.index_type);
  console.log('Metric type:', params.metric_type);
  console.log('Parameters:', params);
}
```

### List Indexes

List all indexes in a collection:

```javascript
const indexes = await client.listIndexes({
  collection_name: 'my_collection',
});

console.log('Indexes:', indexes.indexes);
```

### Get Index State

Check if index is built:

```javascript
const state = await client.getIndexState({
  collection_name: 'my_collection',
  field_name: 'vector',
});

console.log('Index state:', state.state); // 'IndexStateNone', 'IndexStateUnissued', 'IndexStateInProgress', 'IndexStateFinished', 'IndexStateFailed'
```

### Get Index Build Progress

Monitor index build progress:

```javascript
const progress = await client.getIndexBuildProgress({
  collection_name: 'my_collection',
  field_name: 'vector',
});

console.log('Indexed rows:', progress.indexed_rows);
console.log('Total rows:', progress.total_rows);
```

### Alter Index Properties

Release the collection before modifying its index properties:

```javascript
await client.alterIndexProperties({
  collection_name: 'my_collection',
  index_name: 'vector_idx',
  params: {
    'mmap.enabled': true,
  },
});
```

### Drop Index Properties

Remove index properties:

```javascript
await client.dropIndexProperties({
  collection_name: 'my_collection',
  index_name: 'vector_idx',
  properties: ['mmap.enabled'],
});
```

### Drop Index

Delete an index:

```javascript
await client.dropIndex({
  collection_name: 'my_collection',
  field_name: 'vector',
});
```

## Index Best Practices

### Choosing an Index Type

1. **Small datasets (< 1M vectors)**: Use FLAT for exact search
2. **Medium datasets (1M - 10M vectors)**: Use HNSW for high recall
3. **Large datasets (> 10M vectors)**: Use IVF_PQ for memory efficiency
4. **High-dimensional vectors**: Prefer HNSW or IVF_FLAT
5. **Memory-constrained**: Use IVF_SQ8 or IVF_PQ
6. **Binary signatures / set similarity**: Use MINHASH_LSH with JACCARD

### Index Parameters

**HNSW Parameters:**

- `M`: Higher values improve recall but increase memory (typical: 16-32)
- `efConstruction`: Higher values improve index quality but slower build (typical: 100-500)

**IVF Parameters:**

- `nlist`: Number of clusters (typical: sqrt(total_vectors) to total_vectors/10)

**IVF_PQ Parameters:**

- `m`: Number of sub-vectors (typical: 8-16)
- `nbits`: Bits per sub-vector (typical: 8)

### Metric Type Selection

- **L2**: Use for embeddings trained with L2 distance
- **IP**: Use for embeddings trained with inner product
- **COSINE**: Use for normalized embeddings
- **HAMMING/JACCARD**: Use for binary vectors
- **JACCARD + MINHASH_LSH**: Use for binary signatures and set-similarity workloads

### Index Building

1. **Build after insertion**: Create index after inserting data
2. **Monitor progress**: Check build progress for large datasets
3. **Load after indexing**: Load collection after index is built
4. **One index per vector field**: Each vector field can have one index

## Complete Example

```javascript
// Create collection
await client.createCollection({
  collection_name: 'my_collection',
  fields: [
    {
      name: 'id',
      data_type: DataType.Int64,
      is_primary_key: true,
      autoID: true,
    },
    {
      name: 'vector',
      data_type: DataType.FloatVector,
      dim: 128,
    },
  ],
});

// Insert data
await client.insert({
  collection_name: 'my_collection',
  data: [
    /* ... */
  ],
});

// Create index
await client.createIndex({
  collection_name: 'my_collection',
  field_name: 'vector',
  index_type: 'HNSW',
  metric_type: 'L2',
  params: {
    M: 16,
    efConstruction: 200,
  },
});

// Wait for index to be built
let state;
do {
  state = await client.getIndexState({
    collection_name: 'my_collection',
    field_name: 'vector',
  });
  await new Promise((resolve) => setTimeout(resolve, 1000));
} while (state.state !== 'IndexStateFinished');

// Load collection
await client.loadCollectionSync({
  collection_name: 'my_collection',
});

// Now you can search
const results = await client.search({
  collection_name: 'my_collection',
  data: [
    /* vector */
  ],
  limit: 10,
});
```

## Next Steps

- Learn about [Data Operations](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-insert/)
- Explore [Search Operations](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/)
- Check out [Best Practices](https://milvus-io.github.io/milvus-sdk-node/advanced/best-practices/)

## Additional index enums in SDK 3.0.5

| Enum | Purpose |
| --- | --- |
| `IndexType.HNSW_SQ` | HNSW with scalar quantization |
| `IndexType.HNSW_PQ` | HNSW with product quantization |
| `IndexType.HNSW_PRQ` | HNSW with product residual quantization |
| `IndexType.AISAQ` | DiskANN variant with PQ codes stored with the graph |
| `IndexType.NGRAM` | N-gram scalar index for VarChar / JSON paths, accelerating LIKE |
| `IndexType.FMINDEX` | FM-index for VarChar pattern matching |

Use these constants as `createIndex({ index_type: IndexType.HNSW_SQ, ... })` values. The enum additions do not enable an index on older servers; consult your server’s supported index types and parameters. Legacy enum members remain for compatibility and do not guarantee current server support.
