Skip to content

Commit

Permalink
Update readme for 2024-07 release (#242)
Browse files Browse the repository at this point in the history 
## Problem

Some items in our README are stale.

## Solution

Update 'em!

## Outstanding questions: 
- ~I noticed that we don't have an explicit example for creating a pod
index from collection. Do we want to add?~ Yes we do, oops!
- Do we want to move the 'upserting vectors' section earlier in the
README? It struck me as strange as a reader that the **metadata typing**
section deals with upserting vectors, but we don't show how to upsert
vectors until later.


## Type of Change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [ ] This change requires a documentation update
- [ ] Infrastructure change (CI configs, etc)
- [x] Non-code change (docs, etc)
- [ ] None of the above: (explain here)

---------

Co-authored-by: Austin DeNoble <[email protected]>
  • Loading branch information
@aulorbe @austin-denoble
aulorbe and austin-denoble committed Jul 19, 2024
1 parent 3771e73 commit 02370e5
Showing 1 changed file with 92 additions and 65 deletions.
157 changes: 92 additions & 65 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,7 @@ await pc.describeIndex('serverless-index');
// dimension: 1536,
// metric: 'cosine',
// host: 'serverless-index-4zo0ijk.svc.us-west2-aws.pinecone.io',
// deletionProtection: 'disabled',
// spec: {
// serverless: {
// cloud: 'aws',
Expand All @@ -145,24 +146,6 @@ await pc.describeIndex('serverless-index');
// state: 'Initializing'
// }
// }

await pc.describeIndex('serverless-index');
// {
// name: 'serverless-index',
// dimension: 1536,
// metric: 'cosine',
// host: 'serverless-index-4zo0ijk.svc.us-west2-aws.pinecone.io',
// spec: {
// serverless: {
// cloud: 'aws',
// region: 'us-west-2'
// }
// },
// status: {
// ready: true,
// state: 'Ready'
// }
// }
```

#### Waiting until the index is ready
Expand All @@ -174,15 +157,15 @@ import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

await pc.createIndex({
name: 'serverless-index',
dimension: 1536,
spec: {
serverless: {
cloud: 'aws',
region: 'us-west-2',
}
}
waitUntilReady: true,
name: 'serverless-index',
dimension: 1536,
spec: {
serverless: {
cloud: 'aws',
region: 'us-west-2',
},
},
waitUntilReady: true,
});
```

Expand Down Expand Up @@ -211,24 +194,25 @@ await pc.describeCollection('product-description-embeddings');
// }
```

You can specify a sourceCollection along with other configuration in your `createIndex` options:
**Note:** For pod-based indexes, you can specify a `sourceCollection` from which to create an index. The
collection must be in the same environment as the index.

```typescript
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

await pc.createIndex({
name: 'product-description-p1x1',
dimension: 256,
metric: 'cosine'
spec: {
pod: {
environment: 'us-east4-gcp',
pods: 1,
podType: 'p1.x1',
sourceCollection: 'product-description-embeddings',
}
}
name: 'product-description-p1x1',
dimension: 256,
metric: 'cosine',
spec: {
pod: {
environment: 'us-east4-gcp',
pods: 1,
podType: 'p1.x1',
sourceCollection: 'product-description-embeddings',
},
},
});
```

Expand All @@ -247,6 +231,39 @@ await pc.index('product-description-p2x2').describeIndexStats();
// }
```

#### Create or configure an index with deletion protection

You can configure both serverless and pod indexes with `deletionProtection`. Any index with this property set to `'enabled'` will be unable to be deleted. By default, `deletionProtection` will be set to `'disabled'` if not provided as a part of the `createIndex` request. To enable `deletionProtection` you can pass the value while calling `createIndex`.

```typescript
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

await pc.createIndex({
name: 'deletion-protected-index',
dimension: 1536,
metric: 'cosine',
deletionProtection: 'enabled',
spec: {
serverless: {
cloud: 'aws',
region: 'us-west-2',
},
},
});
```

To disable deletion protection, you can use the `configureIndex` operation.

```typescript
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

await pc.configureIndex('deletion-protected-index', {
deletionProtection: 'disabled',
});
```

### Describe Index

You can fetch the description of any index by name using `describeIndex`.
Expand All @@ -261,11 +278,12 @@ await pc.describeIndex('serverless-index');
// dimension: 1536,
// metric: 'cosine',
// host: 'serverless-index-4zo0ijk.svc.us-west2-aws.pinecone.io',
// deletionProtection: 'disabled',
// spec: {
// serverless: {
// cloud: 'aws',
// region: 'us-west-2'
// }
// },
// },
// status: {
// ready: true,
Expand All @@ -285,21 +303,30 @@ You can adjust the number of replicas or scale to a larger pod size (specified w
```typescript
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

await pc.configureIndex('pod-index', { replicas: 3 });
await pc.configureIndex('pod-index', {
spec: {
pod: {
replicas: 2,
podType: 'p1.x4',
},
},
});
const config = await pc.describeIndex('pod-index');
// {
// name: 'pod-index',
// dimension: 1536,
// metric: 'cosine',
// host: 'serverless-index-4zo0ijk.svc.us-west2-aws.pinecone.io',
// host: 'pod-index-4zo0ijk.svc.us-east1-gcp.pinecone.io',
// deletionProtection: 'disabled',
// spec: {
// pod: {
// environment: 'us-east1-gcp',
// pods: 3,
// replicas: 3,
// shards: 1,
// podType: 'p1.x1'
// replicas: 2,
// shards: 2,
// podType: 'p1.x4',
// pods: 4,
// metadataConfig: [Object],
// sourceCollection: undefined
// }
// },
// status: {
Expand Down Expand Up @@ -336,6 +363,7 @@ await pc.listIndexes();
// dimension: 1536,
// metric: 'cosine',
// host: 'serverless-index-4zo0ijk.svc.us-west2-aws.pinecone.io',
// deletionProtection: 'disabled',
// spec: {
// serverless: {
// cloud: 'aws',
Expand All @@ -352,6 +380,7 @@ await pc.listIndexes();
// dimension: 1536,
// metric: 'cosine',
// host: 'pod-index-4zo0ijk.svc.us-west2-aws.pinecone.io',
// deletionProtection: 'disabled',
// spec: {
// pod: {
// environment: 'us-west2-aws',
Expand Down Expand Up @@ -415,7 +444,8 @@ const describeCollection = await pc.describeCollection('collection3');
// size: 3126700,
// status: 'Ready',
// dimension: 3,
// recordCount: 99
// vectorCount: 1234,
// environment: 'us-east1-gcp',
// }
```

Expand Down Expand Up @@ -467,7 +497,9 @@ const index = pc.index('test-index');
await index.fetch(['1']);
```

The first argument is the name of the index you are targeting. There's an optional second argument for providing an index host override for all index operations.
The first argument is the name of the index you are targeting. There's an optional second argument for providing an
index host override. Providing this second argument allows you to bypass the SDK's default behavior of resolving
your index host via the provided index name. You can find your index host in the [Pinecone console](https://app.pinecone.io), or by using the `describeIndex` or `listIndexes` operations.

```typescript
import { Pinecone } from '@pinecone-database/pinecone';
Expand All @@ -483,12 +515,12 @@ await index.fetch(['1']);
If you are storing metadata alongside your vector values, you can pass a type parameter to `index()` in order to get proper TypeScript typechecking.

```typescript
import { Pinecone } from '@pinecone-database/pinecone';
import { Pinecone, PineconeRecord } from '@pinecone-database/pinecone';
const pc = new Pinecone();

type MovieMetadata = {
title: string,
runtime: numbers,
runtime: number,
genre: 'comedy' | 'horror' | 'drama' | 'action'
}

Expand Down Expand Up @@ -540,16 +572,6 @@ const index = pc.index('test-index').namespace('ns1');
await index.fetch(['1']);
```

If needed, you can check the currently targeted index and namespace by inspecting the `target` property of an index object.

```typescript
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index('test-index').namespace('ns1');

console.log(index.target); // { index: 'test-index', namespace: 'ns1', indexHostUrl: undefined }
```

See [Use namespaces](https://docs.pinecone.io/guides/indexes/use-namespaces) for more information.

### Upsert records
Expand Down Expand Up @@ -581,10 +603,12 @@ const records = [
{
id: '1',
values: [0.236, 0.971, 0.559],
sparseValues: { indices: [0, 1], values: [0.236, 0.34] }, // Optional; for hybrid search
},
{
id: '2',
values: [0.685, 0.111, 0.857],
sparseValues: { indices: [0, 1], values: [0.345, 0.98] }, // Optional; for hybrid search
},
];

Expand Down Expand Up @@ -674,9 +698,10 @@ await index.query({ topK: 3, vector: [0.22, 0.66] });
// }
```

You include options to `includeMetadata: true` or `includeValues: true` if you need this information. By default these are not returned to keep the response payload small.
You include options to `includeMetadata: true` or `includeValues: true` if you need this information. By default,
these are not returned to keep the response payload small.

Remember that data operations take place within the context of a namespace, so if you are working with namespaces and do not see expected results you should check that you are targeting the correct namespace with your query.
Remember that data operations take place within the context of a `namespace`, so if you are working with namespaces and do not see expected results you should check that you are targeting the correct namespace with your query.

```typescript
import { Pinecone } from '@pinecone-database/pinecone';
Expand Down Expand Up @@ -715,7 +740,7 @@ await pc.createIndex({
spec: {
pod: {
environment: 'us-west4-gcp',
pods: 1
pods: 1,
podType: 's1.x1',
}
},
Expand Down Expand Up @@ -785,7 +810,7 @@ console.log(results);
// Fetch the next page of results
await index.listPaginated({
prefix: 'doc1#',
paginationToken: results.pagination.next,
paginationToken: results.pagination?.next,
});
```

Expand Down Expand Up @@ -825,6 +850,8 @@ await index.deleteMany(['id-1', 'id-2', 'id-3']);

### Delete many by metadata filter

**Note:** deletion by metadata filter only applies to pod-based indexes.

```typescript
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
Expand Down

0 comments on commit 02370e5

Please sign in to comment.