# Query Entities and Search Vectors

Query by scalar filter or primary key and run vector similarity searches in Milvus using 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/operations/data-operations-query/

## Section links

- [Query Operations](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#query-operations)
- [Basic Query](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#basic-query)
- [Query by IDs](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#query-by-ids)
- [Query with Limit, Offset, and Ordering](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#query-with-limit-offset-and-ordering)
- [Query Specific Partitions](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#query-specific-partitions)
- [Query Iterator](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#query-iterator)
- [Get Operation](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#get-operation)
- [Count Operation](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#count-operation)
- [Query Aggregation](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#query-aggregation)
- [Search Operations](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#search-operations)
- [Basic Search](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#basic-search)
- [Search Aggregation](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#search-aggregation)
- [Search by ID](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#search-by-id)
- [Search Multiple Vectors](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#search-multiple-vectors)
- [Search with Filter](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#search-with-filter)
- [Search with Ordering](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#search-with-ordering)
- [Search Parameters](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#search-parameters)
- [Search Specific Partitions](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#search-specific-partitions)
- [Search Iterator](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#search-iterator)
- [Hybrid Search](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#hybrid-search)
- [Filter Expressions](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#filter-expressions)
- [Comparison Operators](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#comparison-operators)
- [Logical Operators](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#logical-operators)
- [In Operator](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#in-operator)
- [String Operations](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#string-operations)
- [JSON Field Access](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#json-field-access)
- [StructArray Element Filters](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#structarray-element-filters)
- [Regex, Raw Strings, and Bitwise Operators Milvus 3.0](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#regex-raw-strings-and-bitwise-operators-milvus-30)
- [Search Results](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#search-results)
- [Element-Level Offsets Milvus 3.0](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#element-level-offsets-milvus-30)
- [Output Fields](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#output-fields)
- [Performance Optimization](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#performance-optimization)
- [Search Parameters Tuning](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#search-parameters-tuning)
- [Batch Search](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#batch-search)
- [Pre-load Collections](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#pre-load-collections)
- [Best Practices](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#best-practices)
- [Complete Example](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#complete-example)
- [Next Steps](https://milvus-io.github.io/milvus-sdk-node/operations/data-operations-query/#next-steps)

Use `get` to fetch known primary keys, `query` to match scalar filters, `search` to rank by vector similarity, and `hybridSearch` to combine similarity searches. Use an iterator when you need results in batches. Load the collection before reading it.

| Method | Use it to | Main input |
| --- | --- | --- |
| `get` | Fetch entities by primary key | `ids` |
| `query` | Read rows matching a scalar expression | `filter`, or `limit` for an unfiltered read |
| `search` | Return the nearest vector matches | Query vectors in `data`, optional scalar `filter` |
| `hybridSearch` | Fuse multiple ANN searches and rerank the candidates | Sub-searches in `data` and a `rerank` strategy |
| `queryIterator` / `searchIterator` | Read a large scalar query or vector search in batches | The query or search inputs and `batchSize` |

Use `filter` for scalar expressions in `query`, `search`, and iterators. Those APIs also accept `expr` as an alias.

## Query Operations

Query retrieves entities based on filter expressions.

### Basic Query

Query entities with a filter expression:

```javascript
const results = await client.query({
  collection_name: 'my_collection',
  filter: 'age > 25',
  output_fields: ['id', 'vector', 'text'],
});
```

### Query by IDs

Query specific entities by their IDs:

```javascript
const results = await client.query({
  collection_name: 'my_collection',
  ids: [1, 2, 3, 4, 5],
  output_fields: ['id', 'vector', 'text'],
});
```

### Query with Limit, Offset, and Ordering

```javascript
const results = await client.query({
  collection_name: 'my_collection',
  filter: 'age > 25',
  output_fields: ['id', 'text', 'price'],
  limit: 10,
  offset: 0,
  order_by_fields: [{ field: 'price', order: 'desc' }],
});
```

`order_by_fields` can be a string, an array of strings, or an array of `{ field, order }` objects. Milvus requires an explicit `limit` for ordered queries:

```javascript
await client.query({
  collection_name: 'my_collection',
  filter: 'age > 25',
  output_fields: ['id', 'price', 'rating'],
  limit: 10,
  order_by_fields: 'price:asc,rating:desc',
});

await client.query({
  collection_name: 'my_collection',
  filter: 'age > 25',
  output_fields: ['id', 'price', 'rating'],
  limit: 10,
  order_by: ['price:asc', { field: 'rating', order: 'desc' }], // alias
});
```

### Query Specific Partitions

```javascript
const results = await client.query({
  collection_name: 'my_collection',
  filter: 'age > 25',
  partition_names: ['partition_1', 'partition_2'],
  output_fields: ['id', 'text'],
});
```

### Query Iterator

Iterate through large result sets:

```javascript
const iterator = await client.queryIterator({
  collection_name: 'my_collection',
  filter: 'age > 25',
  output_fields: ['id', 'text'],
  batchSize: 100,
});

for await (const batch of iterator) {
  console.log('Batch:', batch);
}
```

## Get Operation

Get entities by IDs (simpler than query):

```javascript
const results = await client.get({
  collection_name: 'my_collection',
  ids: [1, 2, 3],
  output_fields: ['id', 'vector', 'text'],
});
```

## Count Operation

Count entities matching a filter:

```javascript
const result = await client.count({
  collection_name: 'my_collection',
  filter: 'age > 25',
});

if (result.status.error_code !== 'Success') {
  throw new Error(result.status.reason);
}
console.log('Count:', result.data);
```

### Query Aggregation

 Milvus 3.0 

Put aggregation expressions in `output_fields`. Add `group_by_fields` when you want one result row per scalar group.

```javascript
const result = await client.query({
  collection_name: 'sales',
  filter: 'price > 0',
  group_by_fields: ['category'],
  output_fields: [
    'category',
    'count(price)',
    'min(price)',
    'max(price)',
    'sum(price)',
    'avg(price)',
  ],
  limit: 20,
});

result.data.forEach((row) => {
  console.log(row.category, row['count(price)'], row['avg(price)']);
});
```

The supported functions are `count`, `min`, `max`, `sum`, and `avg`. Without `group_by_fields`, Milvus returns collection-level aggregation values.

## Search Operations

Search finds similar vectors using distance metrics.

### Basic Search

```javascript
const results = await client.search({
  collection_name: 'my_collection',
  data: [[0.1, 0.2, 0.3, 0.4]], // Search vector
  limit: 10,
  output_fields: ['id', 'text'],
});
```

### Search Aggregation

 Milvus 3.0 

Search aggregation groups the candidate set into buckets. Each bucket can include metrics, sorted top hits, and nested sub-aggregations.

```javascript
const results = await client.search({
  collection_name: 'products',
  anns_field: 'embedding',
  data: [0.1, 0.2, 0.3, 0.4],
  limit: 100,
  filter: 'in_stock == true',
  output_fields: ['category', 'brand', 'price'],
  search_aggregation: {
    fields: ['category'],
    size: 5,
    metrics: {
      item_count: { op: 'count', field_name: '*' },
      average_price: { op: 'avg', field_name: 'price' },
    },
    order: [{ key: 'average_price', direction: 'desc' }],
    top_hits: {
      size: 2,
      sort: [{ field_name: 'price', direction: 'asc' }],
    },
    sub_aggregation: {
      fields: ['brand'],
      size: 3,
    },
  },
});

console.log(results.agg_buckets);
```

For one query vector, `agg_buckets` is an `AggregationBucket[]`. For multiple query vectors, it is an `AggregationBucket[][]`. Aggregation searches return their grouped data through `agg_buckets` instead of regular hit rows. Search aggregation is not available for hybrid search and cannot be combined with highlighters, grouping, or a positive offset.

### Search by ID

perform a vector similarity search using the vectors associated with exact entity IDs:

```javascript
const results = await client.search({
  collection_name: 'my_collection',
  ids: [1, 2, 3], // primary keys
  limit: 10,
  output_fields: ['id', 'text'],
});
```

> [!NOTE]
> 
> - When `ids` are provided, the `data` parameter (dummy vectors) is not required.
> - The provided `ids` must match the collection’s Primary Key type (`Int64` or `VarChar`).
> - For collections with multiple vector fields, explicitly specifying `anns_field` is recommended (and required to disambiguate).

### Search Multiple Vectors

```javascript
const results = await client.search({
  collection_name: 'my_collection',
  data: [
    [0.1, 0.2, 0.3, 0.4],
    [0.5, 0.6, 0.7, 0.8],
  ],
  limit: 10,
  output_fields: ['id', 'text'],
});
```

### Search with Filter

Combine vector search with scalar filters:

```javascript
const results = await client.search({
  collection_name: 'my_collection',
  data: [[0.1, 0.2, 0.3, 0.4]],
  filter: 'age > 25 AND category == "tech"',
  limit: 10,
  output_fields: ['id', 'text', 'age'],
});
```

### Search with Ordering

Sort search results by scalar fields after vector retrieval:

```javascript
const results = await client.search({
  collection_name: 'my_collection',
  data: [[0.1, 0.2, 0.3, 0.4]],
  limit: 10,
  output_fields: ['id', 'price', 'rating'],
  order_by_fields: [
    { field: 'price', order: 'asc' },
    { field: 'rating', order: 'desc' },
  ],
});
```

You can also pass `order_by_fields` as a string, for example `'price:asc,rating:desc'`. If you also pass `params.order_by_fields`, the top-level `order_by_fields` value takes precedence.

### Search Parameters

Configure search parameters for different index types:

```javascript
// For IVF indexes
const ivfResults = await client.search({
  collection_name: 'my_collection',
  data: [[0.1, 0.2, 0.3, 0.4]],
  params: {
    nprobe: 64, // Number of clusters to search
  },
  limit: 10,
});

// For HNSW indexes
const hnswResults = await client.search({
  collection_name: 'my_collection',
  data: [[0.1, 0.2, 0.3, 0.4]],
  params: {
    ef: 100, // Search width
  },
  limit: 10,
});
```

### Search Specific Partitions

```javascript
const results = await client.search({
  collection_name: 'my_collection',
  data: [[0.1, 0.2, 0.3, 0.4]],
  partition_names: ['partition_1'],
  limit: 10,
});
```

### Search Iterator

Iterate through large search results:

```javascript
const iterator = await client.searchIterator({
  collection_name: 'my_collection',
  data: [[0.1, 0.2, 0.3, 0.4]],
  filter: 'age > 25',
  limit: 1000,
  batchSize: 100,
});

for await (const batch of iterator) {
  console.log('Batch:', batch);
}
```

### Hybrid Search

Search with multiple vector fields:

```javascript
const results = await client.hybridSearch({
  collection_name: 'my_collection',
  data: [
    {
      data: [0.1, 0.2, 0.3, 0.4],
      anns_field: 'text_vector',
    },
    {
      data: [0.5, 0.6, 0.7, 0.8],
      anns_field: 'image_vector',
    },
  ],
  rerank: { strategy: 'rrf', params: { k: 60 } },
  limit: 10,
  output_fields: ['id', 'text'],
});
```

## Filter Expressions

Filter expressions use Milvus expression syntax:

### Comparison Operators

```javascript
'age > 25';
'age >= 25';
'age < 25';
'age <= 25';
'age == 25';
'age != 25';
```

### Logical Operators

```javascript
'age > 25 AND category == "tech"';
'age > 25 OR age < 18';
'NOT (age > 25)';
```

### In Operator

```javascript
'id in [1, 2, 3, 4, 5]';
'category in ["tech", "science"]';
```

### String Operations

```javascript
'text like "milvus%"';
'text like "%database%"';
```

### JSON Field Access

```javascript
'metadata.category == "tech"';
'metadata.tags[0] == "ai"';
```

### StructArray Element Filters

 Milvus 3.0 

Use `element_filter` and `$[...]` to apply predicates to fields in the same StructArray element:

```javascript
'element_filter(profile, $[score] >= 90 AND $[active] == true)';
```

Select child fields with bracketed paths such as `profile[score]` and `profile[tag]`. Element-level query and search results include an `offset` identifying the matching array element.

### Regex, Raw Strings, and Bitwise Operators Milvus 3.0

These expressions are passed through to the Milvus expression parser:

```javascript
// Regular expression match and negative match
'name =~ "^milvus-[0-9]+$"';
'name !~ "-archived$"';

// Raw string literal for patterns with backslashes
'path == r"C:\\data\\vectors"';

// Bitwise AND, OR, and XOR
'(permissions & 4) != 0';
'(flags | 2) == 3';
'(mask ^ 1) == 0';
```

## Search Results

Search results include:

```javascript
const results = await client.search({
  collection_name: 'my_collection',
  data: [[0.1, 0.2, 0.3, 0.4]],
  limit: 10,
});

results.results.forEach((result) => {
  console.log('ID:', result.id);
  console.log('Distance:', result.distance);
  console.log('Score:', result.score);
  console.log('Entity:', result.entity);
});
```

### Element-Level Offsets Milvus 3.0

For element-level retrieval, Milvus can return the matching element offsets for array or multi-vector fields. The SDK flattens `element_indices` into result rows and adds an `offset` property that identifies the matched element within the source field.

```javascript
const results = await client.search({
  collection_name: 'chunked_docs',
  data: [
    [
      /* query vector */
    ],
  ],
  anns_field: 'chunk_embeddings',
  limit: 10,
  output_fields: ['doc_id', 'title'],
});

results.results.forEach((row) => {
  console.log('Document:', row.doc_id);
  console.log('Matched element offset:', row.offset);
});
```

Grouped search responses can also include `group_by_field_values`, which the SDK exposes on each result row:

```javascript
results.results.forEach((row) => {
  console.log('Score:', row.score);
  console.log('Group by values:', row.group_by_field_values);
});
```

## Output Fields

Specify which fields to return:

```javascript
// Return specific fields
output_fields: ['id', 'text', 'age'];

// Return all fields
output_fields: ['*'];

// Return vector fields
output_fields: ['id', 'vector'];
```

## Performance Optimization

### Search Parameters Tuning

**IVF indexes:**

- `nprobe`: Higher values improve recall but slower (typical: 16-256)

**HNSW indexes:**

- `ef`: Higher values improve recall but slower (typical: 50-200)

### Batch Search

Search multiple vectors efficiently:

```javascript
const results = await client.search({
  collection_name: 'my_collection',
  data: [
    [
      /* vector 1 */
    ],
    [
      /* vector 2 */
    ],
    [
      /* vector 3 */
    ],
  ],
  limit: 10,
});
```

### Pre-load Collections

Load collections before searching:

```javascript
await client.loadCollectionSync({
  collection_name: 'my_collection',
});

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

## Best Practices

1. **Use appropriate limits**: Set reasonable limits to avoid large result sets
2. **Filter before search**: Use filter expressions to narrow down results
3. **Tune search parameters**: Adjust nprobe/ef based on your recall/performance needs
4. **Use iterators**: For large result sets, use query/search iterators
5. **Load collections**: Always load collections before searching
6. **Batch operations**: Search multiple vectors in one call when possible

## Complete Example

Use a collection named `my_collection` with an indexed 128-dimensional vector field and scalar fields named `id`, `text`, and `age`. Insert rows with ages above and below 25 to see how the filter changes the results.

```javascript
import { MilvusClient } from '@zilliz/milvus2-sdk-node';

const client = new MilvusClient({
  address: 'localhost:19530',
});

await client.connectPromise;

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

// Query
const queryResults = await client.query({
  collection_name: 'my_collection',
  filter: 'age > 25',
  output_fields: ['id', 'text', 'age'],
  limit: 10,
});

console.log('Query results:', queryResults.data);

// Search
const searchResults = await client.search({
  collection_name: 'my_collection',
  data: [Array.from({ length: 128 }, () => Math.random())],
  filter: 'age > 25',
  limit: 10,
  output_fields: ['id', 'text'],
});

console.log('Search results:', searchResults.results);
await client.closeConnection();
```

## Next Steps

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