1. Defining Indexed Fields
Example: Pod Selective Indexing
from pinecone import PodSpec
pc.create_index(
name="docs",
dimension=1536,
metric="cosine",
spec=PodSpec(
environment="us-east-1-aws",
pod_type="p1.x1",
metadata_config={"indexed": ["source", "language", "published"]},
),
)
| Note | Detail |
|---|
| Pod only | Serverless indexes all fields |
| Set at creation | Cannot change later |
2. Indexing String Fields
| Recommendation | Reason |
|---|
| Low cardinality | Faster filters (e.g., enums) |
| Avoid free text | Use sparse vectors instead |
| Case-sensitive | Normalize before storing |
3. Indexing Numeric Fields
| Use | Example |
|---|
| Range filter | price, timestamp, score |
| Equality | year, version |
4. Indexing Boolean Fields
| Pattern | Use |
|---|
| published / draft | Visibility filter |
| deleted / active | Soft delete |
| featured | Boost / curate |
Note: Non-indexed metadata is returned with results but cannot be used in filter. Useful for large text snippets or auxiliary data.
| Field Type | Why Skip Indexing |
|---|
| Long text snippet | Bloats filter index, never filtered |
| Source URL | Display only |
| JSON blob | Stored but not filterable |
6. Configuring at Index Creation
Example: Node.js Pod with Indexed Fields
await pc.createIndex({
name: "docs",
dimension: 1536,
metric: "cosine",
spec: { pod: { environment: "us-east-1-aws", podType: "p1.x1",
metadataConfig: { indexed: ["source", "language"] } } },
});
| Aspect | Effect |
|---|
| Index size | Grows with indexed fields × cardinality |
| Query latency | Lower with selective indexing |
| Upsert speed | Slower with many indexed fields |
| Tip | Reason |
|---|
| Index only filtered fields | Smaller, faster index |
| Bucket high-cardinality numbers | e.g., price range buckets |
| Use booleans/enums | Highest filter performance |
| Limit | Workaround |
|---|
| 40 KB / vector | Store large text externally; keep ID reference |
| Field count | No hard limit; size cap applies |
Schema Migration
- Add new field to upsert pipeline (backward compatible).
- Backfill existing vectors with
update(set_metadata=...).
- Switch read path to use new field.
- Remove old field reads; optionally backfill removal.
| Change Type | Strategy |
|---|
| Add field | Backfill or default-on-read |
| Rename field | Write both, migrate readers, drop old |
| Re-type field | Recreate index (no in-place type change) |