Number Field
A number field is a scalar field that stores numeric values. These values can be whole numbers (integers) or decimal numbers (floating-point numbers). They are typically used to represent quantities, measurements, or any data that needs to be mathematically processed.
The table below describes the data types of number fields available in Zilliz Cloud clusters.
Field Type | Description |
---|---|
| Boolean type for storing |
| 8-bit integer, suitable for storing small-range integer data. |
| 16-bit integer, for medium-range integer data. |
| 32-bit integer, ideal for general integer data storage like product quantities or user IDs. |
| 64-bit integer, suitable for storing large-range data like timestamps or identifiers. |
| 32-bit floating-point number, for data requiring general precision, such as ratings or temperature. |
| 64-bit double-precision floating-point number, for high-precision data like financial information or scientific calculations. |
To declare a number field, simply set the datatype
to one of the available numeric data types. For example, DataType.INT64
for an integer field or DataType.FLOAT
for a floating-point field.
Zilliz Cloud supports null values and default values for number fields. To enable these features, set nullable
to True
and default_value
to a numeric value. For details, refer to Nullable & Default.
Add number field
To store numeric data, define a number field in your collection schema. Below is an example of a collection schema with two number fields:
-
age
: stores integer data, allows null values, and has a default value of18
. -
price
: stores float data, allows null values, but does not have a default value.
If you set enable_dynamic_fields=True
when defining the schema, Zilliz Cloud allows you to insert scalar fields that were not defined in advance. However, this may increase the complexity of queries and management, potentially impacting performance. For more information, refer to Dynamic Field.
- Python
- Java
- NodeJS
- Go
- cURL
# Import necessary libraries
from pymilvus import MilvusClient, DataType
# Define server address
SERVER_ADDR = "YOUR_CLUSTER_ENDPOINT"
# Create a MilvusClient instance
client = MilvusClient(uri=SERVER_ADDR)
# Define the collection schema
schema = client.create_schema(
auto_id=False,
enable_dynamic_fields=True,
)
# Add an INT64 field `age` that supports null values with default value 18
schema.add_field(field_name="age", datatype=DataType.INT64, nullable=True, default_value=18)
# Add a FLOAT field `price` that supports null values without default value
schema.add_field(field_name="price", datatype=DataType.FLOAT, nullable=True)
schema.add_field(field_name="pk", datatype=DataType.INT64, is_primary=True)
schema.add_field(field_name="embedding", datatype=DataType.FLOAT_VECTOR, dim=3)
import io.milvus.v2.client.ConnectConfig;
import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.common.DataType;
import io.milvus.v2.service.collection.request.AddFieldReq;
import io.milvus.v2.service.collection.request.CreateCollectionReq;
MilvusClientV2 client = new MilvusClientV2(ConnectConfig.builder()
.uri("YOUR_CLUSTER_ENDPOINT")
.build());
CreateCollectionReq.CollectionSchema schema = client.createSchema();
schema.setEnableDynamicField(true);
schema.addField(AddFieldReq.builder()
.fieldName("age")
.dataType(DataType.Int64)
.isNullable(true)
.defaultValue(18)
.build());
schema.addField(AddFieldReq.builder()
.fieldName("price")
.dataType(DataType.Float)
.isNullable(true)
.build());
schema.addField(AddFieldReq.builder()
.fieldName("pk")
.dataType(DataType.Int64)
.isPrimaryKey(true)
.build());
schema.addField(AddFieldReq.builder()
.fieldName("embedding")
.dataType(DataType.FloatVector)
.dimension(3)
.build());
import { MilvusClient, DataType } from "@zilliz/milvus2-sdk-node";
const schema = [
{
name: "age",
data_type: DataType.Int64,
},
{
name: "price",
data_type: DataType.Float,
},
{
name: "pk",
data_type: DataType.Int64,
is_primary_key: true,
},
{
name: "embedding",
data_type: DataType.FloatVector,
dim: 3,
},
];
// go
export int64Field='{
"fieldName": "age",
"dataType": "Int64"
}'
export floatField='{
"fieldName": "price",
"dataType": "Float"
}'
export pkField='{
"fieldName": "pk",
"dataType": "Int64",
"isPrimary": true
}'
export vectorField='{
"fieldName": "embedding",
"dataType": "FloatVector",
"elementTypeParams": {
"dim": 3
}
}'
export schema="{
\"autoID\": false,
\"fields\": [
$int64Field,
$floatField,
$pkField,
$vectorField
]
}"
Set index params
Indexing helps improve search and query performance. In Zilliz Cloud clusters, indexing is mandatory for vector fields but optional for scalar fields.
The following example creates indexes on the vector field embedding
and the scalar field age
, both using the AUTOINDEX
index type. With this type, Milvus automatically selects the most suitable index based on the data type.
- Python
- Java
- NodeJS
- Go
- cURL
# Set index params
index_params = client.prepare_index_params()
# Index `age` with AUTOINDEX
index_params.add_index(
field_name="age",
index_type="AUTOINDEX",
index_name="age_index"
)
# Index `embedding` with AUTOINDEX and specify similarity metric type
index_params.add_index(
field_name="embedding",
index_type="AUTOINDEX", # Use automatic indexing to simplify complex index settings
metric_type="COSINE" # Specify similarity metric type, options include L2, COSINE, or IP
)
import io.milvus.v2.common.IndexParam;
import java.util.*;
List<IndexParam> indexes = new ArrayList<>();
indexes.add(IndexParam.builder()
.fieldName("age")
.indexType(IndexParam.IndexType.AUTOINDEX)
.build());
indexes.add(IndexParam.builder()
.fieldName("embedding")
.indexType(IndexParam.IndexType.AUTOINDEX)
.metricType(IndexParam.MetricType.COSINE)
.build());
import { IndexType } from "@zilliz/milvus2-sdk-node";
const indexParams = [
{
field_name: "age",
index_name: "inverted_index",
index_type: IndexType.AUTOINDEX,
},
{
field_name: "embedding",
metric_type: "COSINE",
index_type: IndexType.AUTOINDEX,
},
];
// go
export indexParams='[
{
"fieldName": "age",
"indexName": "inverted_index",
"indexType": "AUTOINDEX"
},
{
"fieldName": "embedding",
"metricType": "COSINE",
"indexType": "AUTOINDEX"
}
]'
Create collection
Once the schema and indexes are defined, create a collection that includes number fields.
- Python
- Java
- NodeJS
- Go
- cURL
# Create Collection
client.create_collection(
collection_name="my_scalar_collection",
schema=schema,
index_params=index_params
)
CreateCollectionReq requestCreate = CreateCollectionReq.builder()
.collectionName("my_scalar_collection")
.collectionSchema(schema)
.indexParams(indexes)
.build();
client.createCollection(requestCreate);
client.create_collection({
collection_name: "my_scalar_collection",
schema: schema,
index_params: indexParams
})
// go
curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/collections/create" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d "{
\"collectionName\": \"my_scalar_collection\",
\"schema\": $schema,
\"indexParams\": $indexParams
}"
Insert data
After creating the collection, insert entities that match the schema.
- Python
- Java
- NodeJS
- Go
- cURL
# Sample data
data = [
{"age": 25, "price": 99.99, "pk": 1, "embedding": [0.1, 0.2, 0.3]},
{"age": 30, "pk": 2, "embedding": [0.4, 0.5, 0.6]}, # `price` field is missing, which should be null
{"age": None, "price": None, "pk": 3, "embedding": [0.2, 0.3, 0.1]}, # `age` should default to 18, `price` is null
{"age": 45, "price": None, "pk": 4, "embedding": [0.9, 0.1, 0.4]}, # `price` is null
{"age": None, "price": 59.99, "pk": 5, "embedding": [0.8, 0.5, 0.3]}, # `age` should default to 18
{"age": 60, "price": None, "pk": 6, "embedding": [0.1, 0.6, 0.9]} # `price` is null
]
client.insert(
collection_name="my_scalar_collection",
data=data
)
import com.google.gson.Gson;
import com.google.gson.JsonObject;
import io.milvus.v2.service.vector.request.InsertReq;
import io.milvus.v2.service.vector.response.InsertResp;
List<JsonObject> rows = new ArrayList<>();
Gson gson = new Gson();
rows.add(gson.fromJson("{\"age\": 25, \"price\": 99.99, \"pk\": 1, \"embedding\": [0.1, 0.2, 0.3]}", JsonObject.class));
rows.add(gson.fromJson("{\"age\": 30, \"pk\": 2, \"embedding\": [0.4, 0.5, 0.6]}", JsonObject.class));
rows.add(gson.fromJson("{\"age\": null, \"price\": null, \"pk\": 3, \"embedding\": [0.2, 0.3, 0.1]}", JsonObject.class));
rows.add(gson.fromJson("{\"age\": 45, \"price\": null, \"pk\": 4, \"embedding\": [0.9, 0.1, 0.4]}", JsonObject.class));
rows.add(gson.fromJson("{\"age\": null, \"price\": 59.99, \"pk\": 5, \"embedding\": [0.8, 0.5, 0.3]}", JsonObject.class));
rows.add(gson.fromJson("{\"age\": 60, \"price\": null, \"pk\": 6, \"embedding\": [0.1, 0.6, 0.9]}", JsonObject.class));
InsertResp insertR = client.insert(InsertReq.builder()
.collectionName("my_scalar_collection")
.data(rows)
.build());
const data = [
{ age: 25, price: 99.99, pk: 1, embedding: [0.1, 0.2, 0.3] },
{ age: 30, price: 149.5, pk: 2, embedding: [0.4, 0.5, 0.6] },
{ age: 35, price: 199.99, pk: 3, embedding: [0.7, 0.8, 0.9] },
];
client.insert({
collection_name: "my_scalar_collection",
data: data,
});
// go
curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/entities/insert" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d '{
"data": [
{"age": 25, "price": 99.99, "pk": 1, "embedding": [0.1, 0.2, 0.3]},
{"age": 30, "price": 149.50, "pk": 2, "embedding": [0.4, 0.5, 0.6]},
{"age": 35, "price": 199.99, "pk": 3, "embedding": [0.7, 0.8, 0.9]}
],
"collectionName": "my_scalar_collection"
}'
Query with filter expressions
After inserting entities, use the query
method to retrieve entities that match the specified filter expressions.
To retrieve entities where the age
is greater than 30:
- Python
- Java
- NodeJS
- Go
- cURL
filter = 'age > 30'
res = client.query(
collection_name="my_scalar_collection",
filter=filter,
output_fields=["age", "price", "pk"]
)
print(res)
# Example output:
# data: [
# "{'age': 45, 'price': None, 'pk': 4}",
# "{'age': 60, 'price': None, 'pk': 6}"
# ]
import io.milvus.v2.service.vector.request.QueryReq;
import io.milvus.v2.service.vector.response.QueryResp;
String filter = "age > 30";
QueryResp resp = client.query(QueryReq.builder()
.collectionName("my_scalar_collection")
.filter(filter)
.outputFields(Arrays.asList("age", "price"))
.build());
System.out.println(resp.getQueryResults());
// Output
//
// [
// QueryResp.QueryResult(entity={price=null, pk=4, age=45}),
// QueryResp.QueryResult(entity={price=null, pk=6, age=60})
// ]
client.query({
collection_name: 'my_scalar_collection',
filter: '30 <= age <= 40',
output_fields: ['age', 'price']
});
// go
curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/entities/query" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d '{
"collectionName": "my_scalar_collection",
"filter": "30 <= age <= 40",
"outputFields": ["age","price"]
}'
## {"code":0,"cost":0,"data":[{"age":30,"pk":2,"price":149.5},{"age":35,"pk":3,"price":199.99}]}
To retrieve entities where the price
is null:
- Python
- Java
- NodeJS
- Go
- cURL
filter = 'price is null'
res = client.query(
collection_name="my_scalar_collection",
filter=filter,
output_fields=["age", "price", "pk"]
)
print(res)
# Example output:
# data: [
# "{'age': 30, 'price': None, 'pk': 2}",
# "{'age': 18, 'price': None, 'pk': 3}",
# "{'age': 45, 'price': None, 'pk': 4}",
# "{'age': 60, 'price': None, 'pk': 6}"
# ]
String filter = "price is null";
QueryResp resp = client.query(QueryReq.builder()
.collectionName("my_scalar_collection")
.filter(filter)
.outputFields(Arrays.asList("age", "price"))
.build());
System.out.println(resp.getQueryResults());
// Output
// [
// QueryResp.QueryResult(entity={price=null, pk=2, age=30}),
// QueryResp.QueryResult(entity={price=null, pk=3, age=18}),
// QueryResp.QueryResult(entity={price=null, pk=4, age=45}),
// QueryResp.QueryResult(entity={price=null, pk=6, age=60})
// ]
// node
const filter = 'price is null';
const res = await client.query({
collection_name:"my_scalar_collection",
filter:filter,
output_fields=["age", "price", "pk"]
});
console.log(res);
// Example output:
// data: [
// "{'age': 18, 'price': None, 'pk': 3}",
// "{'age': 18, 'price': 59.99, 'pk': 5}"
// ]
// go
# restful
To retrieve entities where age
has the value 18
, use the following expression below. As the default value of age
is 18
, the expected result should include entities with age
explicitly set to 18
or with age
set to null.
- Python
- Java
- NodeJS
- Go
- cURL
filter = 'age == 18'
res = client.query(
collection_name="my_scalar_collection",
filter=filter,
output_fields=["age", "price", "pk"]
)
print(res)
# Example output:
# data: [
# "{'age': 18, 'price': None, 'pk': 3}",
# "{'age': 18, 'price': 59.99, 'pk': 5}"
# ]
String filter = "age == 18";
QueryResp resp = client.query(QueryReq.builder()
.collectionName("my_scalar_collection")
.filter(filter)
.outputFields(Arrays.asList("age", "price"))
.build());
System.out.println(resp.getQueryResults());
// Output
// [
// QueryResp.QueryResult(entity={price=null, pk=3, age=18}),
// QueryResp.QueryResult(entity={price=59.99, pk=5, age=18})
// ]
// node
const filter = 'age == 18';
const res = await client.query({
collection_name:"my_scalar_collection",
filter:filter,
output_fields=["age", "price", "pk"]
});
console.log(res);
// Example output:
// data: [
// "{'age': 18, 'price': None, 'pk': 3}",
// "{'age': 18, 'price': 59.99, 'pk': 5}"
// ]
// go
# restful
Vector search with filter expressions
In addition to basic number field filtering, you can combine vector similarity searches with number field filters. For example, the following code shows how to add a number field filter to a vector search:
- Python
- Java
- NodeJS
- Go
- cURL
filter = "25 <= age <= 35"
res = client.search(
collection_name="my_scalar_collection",
data=[[0.3, -0.6, 0.1]],
limit=5,
search_params={"params": {"nprobe": 10}},
output_fields=["age","price"],
filter=filter
)
print(res)
# Example output:
# data: [
# "[{'id': 2, 'distance': -0.2016308456659317, 'entity': {'age': 30, 'price': None}}, {'id': 1, 'distance': -0.23643313348293304, 'entity': {'age': 25, 'price': 99.98999786376953}}]"
# ]
import io.milvus.v2.service.vector.request.SearchReq;
import io.milvus.v2.service.vector.request.data.FloatVec;
import io.milvus.v2.service.vector.response.SearchResp;
String filter = "25 <= age <= 35";
SearchResp resp = client.search(SearchReq.builder()
.collectionName("my_scalar_collection")
.annsField("embedding")
.data(Collections.singletonList(new FloatVec(new float[]{0.3f, -0.6f, 0.1f})))
.topK(5)
.outputFields(Arrays.asList("age", "price"))
.filter(filter)
.build());
System.out.println(resp.getSearchResults());
// Output
//
// [
// [
// SearchResp.SearchResult(entity={price=null, age=30}, score=-0.20163085, id=2),
// SearchResp.SearchResult(entity={price=99.99, age=25}, score=-0.23643313, id=1)
// ]
// ]
await client.search({
collection_name: 'my_scalar_collection',
data: [0.3, -0.6, 0.1],
limit: 5,
output_fields: ['age', 'price'],
filter: '25 <= age <= 35'
});
// go
curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/entities/search" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Content-Type: application/json" \
-d '{
"collectionName": "my_scalar_collection",
"data": [
[0.3, -0.6, 0.1]
],
"annsField": "embedding",
"limit": 5,
"outputFields": ["age", "price"]
}'
## {"code":0,"cost":0,"data":[{"age":35,"distance":-0.19054288,"id":3,"price":199.99},{"age":30,"distance":-0.20163085,"id":2,"price":149.5},{"age":25,"distance":-0.2364331,"id":1,"price":99.99}]}
In this example, we first define a query vector and add a filter condition 25 <= age <= 35
during the search. This ensures that the search results are not only similar to the query vector but also meet the specified age range. For more information, refer to Filtering.