Operations (sample payloads)
Main operations
Create index
This operation deploys a Pinecone index. This is where you specify the measure of similarity, the dimension of vectors to be stored in the index, which cloud provider you would like to deploy with, and more. Sample Input
{
"name": "product-embeddings",
"dimension": 768,
"metric": "cosine",
"spec": {
"pod": {
"environment": "gcp-starter",
"pod_type": "p1.x1",
"replicas": 1,
"shards": 1,
"pods": 1,
"metadata_config": \{
"indexed": [
"category",
"brand",
"price"
]
\}
}
}
}
Sample Output
{
"name": "product-embeddings",
"dimension": 768,
"metric": "cosine",
"host": "product-embeddings-12345.svc.gcp-starter.pinecone.io",
"spec": {
"pod": {
"environment": "gcp-starter",
"replicas": 1,
"shards": 1,
"pod_type": "p1.x1",
"pods": 1,
"metadata_config": \{
"indexed": [
"category",
"brand",
"price"
]
\},
"source_collection": ""
}
},
"status": \{
"ready": true,
"state": "Ready"
\}
}
Delete vectors
The delete operation deletes vectors, by id, from a single namespace. Sample Input
{
"index_host": "my-index-123456.svc.us-west1-gcp.pinecone.io",
"ids": [
"vec1",
"vec2",
"vec3"
],
"namespace": "product_catalog",
"filter": {
"category": "electronics",
"price": {
"$gt": 500
}
}
}
Sample Output
{
"deleted": true
}
Get index
Get a description of an index. Sample Input
{
"index_name": "my-product-catalog"
}
Sample Output
{
"name": "my-product-catalog",
"dimension": 1536,
"metric": "cosine",
"host": "my-product-catalog-12345.svc.us-west1-gcp.pinecone.io",
"spec": {
"pod": {
"environment": "gcp-starter",
"replicas": 1,
"shard": 1,
"pod_type": "p1.x1",
"pods": 1,
"metadata_config": \{
"indexed": [
"category",
"brand"
],
"source_collection": "products"
\}
}
},
"status": \{
"ready": true,
"state": "Ready"
\}
}
Get index stats
The describe_index_stats operation returns statistics about the contents of an index, including the vector count per namespace and the number of dimensions, and the index fullness. Sample Input
{
"index_host": "my-index-123456.svc.us-west1-gcp.pinecone.io",
"filter": {
"genre": "science fiction",
"year": {
"$gte": 2000
}
}
}
Sample Output
{
"namespaces": {
"default": {
"vector_count": 10000
},
"movies": {
"vector_count": 5000
}
},
"dimension": 1536,
"index_fullness": 0.75,
"total_vector_count": 15000
}
List indexes
This operation returns a list of all indexes in a project. Sample Input
{}
Sample Output
{
"indexes": [
{
"name": "product-catalog",
"dimension": 512,
"metric": "cosine",
"host": "product-catalog-12345.svc.us-west1-gcp.pinecone.io",
"spec": {
"pod": {
"environment": "gcp-starter",
"replicas": 1,
"shards": 1,
"pod_type": "s1.x1",
"pods": 1,
"metadata_config": \{
"indexed": [
"category",
"brand",
"price"
]
\},
"source_collection": ""
}
},
"status": \{
"ready": true,
"state": "Ready"
\}
},
{
"name": "customer-embeddings",
"dimension": 768,
"metric": "euclidean",
"host": "customer-embeddings-67890.svc.us-east1-aws.pinecone.io",
"spec": {
"serverless": \{
"cloud": "aws",
"region": "us-east-1"
\}
},
"status": \{
"ready": true,
"state": "Ready"
\}
}
]
}
Query vectors
The query operation searches a namespace, using a query vector. It retrieves the ids of the most similar items in a namespace, along with their similarity scores. Sample Input
{
"index_host": "my-index-123456.svc.us-west1-gcp.pinecone.io",
"namespace": "products",
"topK": 3,
"filter": {
"category": "electronics",
"price": {
"$lte": 1000
}
},
"includeValues": true,
"includeMetadata": true,
"vector": [
0.1,
0.2,
0.3,
0.4,
0.5
]
}
Sample Output
{
"matches": [
{
"id": "prod_001",
"score": 0.95,
"values": [
0.11,
0.21,
0.31,
0.41,
0.51
],
"metadata": \{
"name": "Smartphone X",
"category": "electronics",
"price": 799.99
\}
},
{
"id": "prod_002",
"score": 0.87,
"values": [
0.12,
0.22,
0.32,
0.42,
0.52
],
"metadata": \{
"name": "Laptop Y",
"category": "electronics",
"price": 999.99
\}
},
{
"id": "prod_003",
"score": 0.82,
"values": [
0.13,
0.23,
0.33,
0.43,
0.53
],
"metadata": \{
"name": "Tablet Z",
"category": "electronics",
"price": 599.99
\}
}
],
"namespace": "products",
"usage": {
"readUnits": 3
}
}
Upsert vectors
The upsert operation writes vectors into a namespace. If a new value is upserted for an existing vector id, it will overwrite the previous value. Sample Input
{
"index_host": "my-index-123abc.svc.us-east-1-aws.pinecone.io",
"vectors": [
{
"id": "vec1",
"values": [
0.1,
0.2,
0.3,
0.4,
0.5
],
"sparseValues": \{
"indices": [
1,
3,
5
],
"values": [
0.5,
0.8,
0.2
]
\},
"metadata": \{
"category": "electronics",
"price": 299.99
\}
},
{
"id": "vec2",
"values": [
0.6,
0.7,
0.8,
0.9,
1
],
"metadata": \{
"category": "clothing",
"size": "medium"
\}
}
],
"namespace": "product_catalog"
}
Sample Output
{
"upsertedCount": 2
}