Using namespaces

Pinecone allows you to partition the vectors in an index into namespaces. Queries and other operations are then limited to one namespace, so different requests can search different subsets of your index.

For example, you might want to define a namespace for indexing articles by content, and another for indexing articles by title. For a complete example, see: Semantic Text Search (Example).

Every index is made up of one or more namespaces. Every vector exists in exactly one namespace.

Namespaces are uniquely identified by a namespace name, which almost all operations accept as a parameter to limit their work to the specified namespace. When you don't specify a namespace name for an operation, Pinecone uses the default namespace name of "" (the empty string).

Creating a namespace

A destination namespace can be specified when vectors are upserted. If the namespace doesn't exist, it is created implicitly.

The example below will create a "my-first-namespace" namespace if it doesn’t already exist:

# Upsert vectors while creating a new namespace
index.upsert(vectors=[('id-1', [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1])],
             namespace='my-first-namespace')

await index.upsert({
  vectors: [
    {
      id: "id-1",
      values: [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1],
    },
  ],
  namespace: "my-first-namespace",
});

curl -i -X POST https://YOUR_INDEX-YOUR_PROJECT.svc.YOUR_ENVIRONMENT.pinecone.io/vectors/upsert \
  -H 'Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "vectors": [
      {
        "id": "id-1",
        "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]
      }
    ],
    "namespace": "my-first-namespace"
  }'

Then you can submit queries and other operations specifying that namespace as a parameter. For example, to query the vectors in namespace "my-first-namespace":

index.query(vector=[0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1],
            top_k=1,
            namespace='my-first-namespace')

const queryResponse = await index.query({
  namespace: "my-first-namespace",
  topK: 1,
  vector: [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1],
});
console.log(queryResponse.data);

curl -i -X POST https://YOUR_INDEX-YOUR_PROJECT.svc.YOUR_ENVIRONMENT.pinecone.io/query \
  -H 'Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "topK": 1,
    "vector": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1],
    "namespace": "my-first-namespace"
  }'

Creating more than one namespace

You can create more than one namespace. For example, insert data into separate namespaces:

import numpy as np

# Create three sets of 8-dimensional vectors
vectors_a = np.random.rand(15, 8).tolist()
vectors_b = np.random.rand(20, 8).tolist()
vectors_c = np.random.rand(30, 8).tolist()

# Create ids
ids_a = map(str, np.arange(15).tolist())
ids_b = map(str, np.arange(20).tolist())
ids_c = map(str, np.arange(30).tolist())

# Insert into separate namespaces
index.upsert(vectors=zip(ids_a,vectors_a),namespace='namespace_a')
index.upsert(vectors=zip(ids_b,vectors_b),namespace='namespace_b')

# if no namespaces are specified, the index uses the default namespace
index.upsert(vectors=zip(ids_c,vectors_c))

# At this point, index.describe_index_stats() returns:
# {'dimension': 8,
#  'namespaces': {'': {'vector_count': 30},
#                 'namespace_a': {'vector_count': 15},
#                 'namespace_b': {'vector_count': 20}}}

# No example

Operations across all namespaces

All vector operations apply to a single namespace, with one exception:

The DescribeIndexStatistics operation returns per-namespace statistics about the contents of all namespaces in an index. More details