diff --git a/src/control/createIndex.ts b/src/control/createIndex.ts index d7148441..68445561 100644 --- a/src/control/createIndex.ts +++ b/src/control/createIndex.ts @@ -27,6 +27,7 @@ import { * @see [Understanding indexes](https://docs.pinecone.io/docs/indexes) */ export interface CreateIndexOptions extends Omit { + /** The distance metric to be used for similarity search. You can use 'euclidean', 'cosine', or 'dotproduct'. Defaults to 'cosine'. */ metric?: CreateIndexRequestMetricEnum; /** This option tells the client not to resolve the returned promise until the index is ready to receive data. */ diff --git a/src/control/types.ts b/src/control/types.ts index 5ac0b818..396e4599 100644 --- a/src/control/types.ts +++ b/src/control/types.ts @@ -10,17 +10,6 @@ const positiveInteger = Type.Integer({ minimum: 1 }); // string. To avoid this confusing case, we require lenth > 1. export const IndexNameSchema = nonemptyString; -/** - * Index names are strings composed of: - * - alphanumeric characters - * - hyphens - * - * Index names must be unique within a project and may not start or end with a hyphen. - * - * @see [Understanding indexes](https://docs.pinecone.io/docs/indexes) - */ -export type IndexName = string; - export const PodTypeSchema = nonemptyString; export const ReplicasSchema = positiveInteger; export const PodsSchema = positiveInteger; @@ -53,6 +42,17 @@ export const MetadataConfigSchema = Type.Object( // string. To avoid this confusing case, we require lenth > 1. export const CollectionNameSchema = nonemptyString; +/** + * Index names are strings composed of: + * - alphanumeric characters + * - hyphens + * + * Index names must be unique within a project and may not start or end with a hyphen. + * + * @see [Understanding indexes](https://docs.pinecone.io/docs/indexes) + */ +export type IndexName = string; + /** * Collection names are strings composed of: * - alphanumeric characters diff --git a/src/data/types.ts b/src/data/types.ts index b1475297..6f00a58a 100644 --- a/src/data/types.ts +++ b/src/data/types.ts @@ -128,5 +128,5 @@ export type OperationUsage = { /** * The number of read units consumed by this operation. */ - readUnits?: string; + readUnits?: number; }; diff --git a/src/integration/data/fetch.test.ts b/src/integration/data/fetch.test.ts index 14234e20..8e437aba 100644 --- a/src/integration/data/fetch.test.ts +++ b/src/integration/data/fetch.test.ts @@ -55,5 +55,6 @@ describe('fetch', () => { expect(results.records['0']).toBeDefined(); expect(results.records['1']).toBeDefined(); expect(results.records['2']).toBeDefined(); + expect(results.usage?.readUnits).toBeDefined(); }); }); diff --git a/src/integration/data/query.test.ts b/src/integration/data/query.test.ts index bf476624..148a0225 100644 --- a/src/integration/data/query.test.ts +++ b/src/integration/data/query.test.ts @@ -53,8 +53,11 @@ describe('query', () => { const topK = 2; const assertions = [ - (results) => expect(results.matches).toBeDefined(), - (results) => expect(results.matches?.length).toEqual(topK), + (results) => { + expect(results.matches).toBeDefined(); + expect(results.matches?.length).toEqual(topK); + expect(results.usage.readUnits).toBeDefined(); + }, ]; await assertWithRetries(() => ns.query({ id: '0', topK }), assertions); @@ -74,8 +77,11 @@ describe('query', () => { const topK = 5; const assertions = [ - (results) => expect(results.matches).toBeDefined(), - (results) => expect(results.matches?.length).toEqual(numberOfRecords), + (results) => { + expect(results.matches).toBeDefined(); + expect(results.matches?.length).toEqual(numberOfRecords); + expect(results.usage.readUnits).toBeDefined(); + }, ]; await assertWithRetries(() => ns.query({ id: '0', topK }), assertions); @@ -94,8 +100,10 @@ describe('query', () => { const topK = 2; const assertions = [ - (results) => expect(results.matches).toBeDefined(), - (results) => expect(results.matches?.length).toEqual(0), + (results) => { + expect(results.matches).toBeDefined(); + expect(results.matches?.length).toEqual(0); + }, ]; await assertWithRetries(() => ns.query({ id: '100', topK }), assertions); @@ -115,8 +123,11 @@ describe('query', () => { const topK = 1; const assertions = [ - (results) => expect(results.matches).toBeDefined(), - (results) => expect(results.matches?.length).toEqual(topK), + (results) => { + expect(results.matches).toBeDefined(); + expect(results.matches?.length).toEqual(topK); + expect(results.usage.readUnits).toBeDefined(); + }, ]; await assertWithRetries( @@ -136,8 +147,11 @@ describe('query', () => { const queryVec = Array.from({ length: 5 }, () => Math.random()); const assertions = [ - (results) => expect(results.matches).toBeDefined(), - (results) => expect(results.matches?.length).toEqual(2), + (results) => { + expect(results.matches).toBeDefined(); + expect(results.matches?.length).toEqual(2); + expect(results.usage.readUnits).toBeDefined(); + }, ]; await assertWithRetries( () => diff --git a/src/pinecone-generated-ts-fetch/models/Usage.ts b/src/pinecone-generated-ts-fetch/models/Usage.ts index 65d140e0..4840915a 100644 --- a/src/pinecone-generated-ts-fetch/models/Usage.ts +++ b/src/pinecone-generated-ts-fetch/models/Usage.ts @@ -21,10 +21,10 @@ import { exists, mapValues } from '../runtime'; export interface Usage { /** * The number of read units consumed by this operation. - * @type {string} + * @type {number} * @memberof Usage */ - readUnits?: string; + readUnits?: number; } /** diff --git a/src/pinecone.ts b/src/pinecone.ts index a4707184..6f31a6df 100644 --- a/src/pinecone.ts +++ b/src/pinecone.ts @@ -33,7 +33,7 @@ import type { PineconeConfiguration, RecordMetadata } from './data'; * * ### Initializing the client * - * There are two pieces of configuration required to use the Pinecone client: an API key and environment value. These values can be passed using environment variables or in code through a configuration object. Find your configuration values in the console dashboard at [https://app.pinecone.io](https://app.pinecone.io) + * There is one piece of configuration required to use the Pinecone client: an API key. This value can be passed using environment variables or in code through a configuration object. Find your API key in the console dashboard at [https://app.pinecone.io](https://app.pinecone.io) * * ### Using environment variables * @@ -181,20 +181,24 @@ export class Pinecone { * * @example * ```js - * const indexConfig = await pinecone.describeIndex('my-index') - * console.log(indexConfig) + * const indexModel = await pinecone.describeIndex('my-index') + * console.log(indexModel) * // { - * // database: { - * // name: 'my-index', - * // metric: 'cosine', - * // dimension: 256, - * // pods: 2, - * // replicas: 2, - * // shards: 1, - * // podType: 'p1.x2', - * // metadataConfig: { indexed: [Array] } - * // }, - * // status: { ready: true, state: 'Ready' } + * // name: 'sample-index-1', + * // dimension: 3, + * // metric: 'cosine', + * // host: 'sample-index-1-1390950.svc.apw5-4e34-81fa.pinecone.io', + * // spec: { + * // pod: undefined, + * // serverless: { + * // cloud: 'aws', + * // region: 'us-west-2' + * // } + * // }, + * // status: { + * // ready: true, + * // state: 'Ready' + * // } * // } * ``` * @@ -217,12 +221,47 @@ export class Pinecone { * List all Pinecone indexes * @example * ```js - * const indexes = await pinecone.listIndexes() - * console.log(indexes) - * // [ 'my-index', 'my-other-index' ] + * const indexList = await pinecone.listIndexes() + * console.log(indexList) + * // { + * // indexes: [ + * // { + * // name: "sample-index-1", + * // dimension: 3, + * // metric: "cosine", + * // host: "sample-index-1-1234567.svc.apw5-2e18-32fa.pinecone.io", + * // spec: { + * // serverless: { + * // cloud: "aws", + * // region: "us-west-2" + * // } + * // }, + * // status: { + * // ready: true, + * // state: "Ready" + * // } + * // }, + * // { + * // name: "sample-index-2", + * // dimension: 3, + * // metric: "cosine", + * // host: "sample-index-2-1234567.svc.apw2-5e76-83fa.pinecone.io", + * // spec: { + * // serverless: { + * // cloud: "aws", + * // region: "us-west-2" + * // } + * // }, + * // status: { + * // ready: true, + * // state: "Ready" + * // } + * // } + * // ] + * // } * ``` * - * @returns A promise that resolves to an array of index names + * @returns A promise that resolves to {@link IndexList}. */ async listIndexes() { const indexList = await this._listIndexes(); @@ -243,20 +282,27 @@ export class Pinecone { * Creates a new index. * * @example - * The minimum required configuration to create an index is the index name and dimension. + * The minimum required configuration to create an index is the index `name`, `dimension`, and `spec`. * ```js - * await pinecone.createIndex({ name: 'my-index', dimension: 128 }) + * await pinecone.createIndex({ name: 'my-index', dimension: 128, spec: { serverless: { cloud: 'aws', region: 'us-west-2' }}}) * ``` + * * @example - * In a more expansive example, you can specify the metric, number of pods, number of replicas, and pod type. + * The `spec` object defines how the index should be deployed. For serverless indexes, you define only the cloud and region where the index should be hosted. + * For pod-based indexes, you define the environment where the index should be hosted, the pod type and size to use, and other index characteristics. + * In a more expansive example, you can create a pod-based index by specifying the `pod` spec object with the `environment`, `pods`, `podType`, and `metric` properties. * ```js * await pinecone.createIndex({ * name: 'my-index', * dimension: 1536, * metric: 'cosine', - * pods: 1, - * replicas: 2, - * podType: 'p1.x1' + * spec: { + * pod: { + * environment: 'us-west-2-gcp', + * pods: 1, + * podType: 'p1.x1' + * } + * } * }) * ``` * @@ -266,6 +312,12 @@ export class Pinecone { * await pinecone.createIndex({ * name: 'my-index', * dimension: 1536, + * spec: { + * serverless: { + * cloud: 'aws', + * region: 'us-west-2' + * } + * }, * suppressConflicts: true * }) * ``` @@ -275,7 +327,12 @@ export class Pinecone { * ```js * await pinecone.createIndex({ * name: 'my-index', - * dimension: 1536, + * spec: { + * serverless: { + * cloud: 'aws', + * region: 'us-west-2' + * } + * }, * waitUntilReady: true * }); * @@ -291,6 +348,12 @@ export class Pinecone { * await pinecone.createIndex({ * name: 'my-index', * dimension: 1536, + * spec: { + * serverless: { + * cloud: 'aws', + * region: 'us-west-2' + * } + * }, * metadataConfig: { 'indexed' : ['productName', 'productDescription'] } * }) * ``` @@ -303,7 +366,7 @@ export class Pinecone { * @throws {@link Errors.PineconeConflictError} when attempting to create an index using a name that already exists in your project. * @throws {@link Errors.PineconeBadRequestError} when index creation fails due to invalid parameters being specified or other problem such as project quotas limiting the creation of any additional indexes. * - * @returns A promise that resolves when the request to create the index is completed. Note that the index is not immediately ready to use. You can use the `describeIndex` function to check the status of the index. + * @returns A promise that resolves to {@link IndexModel} when the request to create the index is completed. Note that the index is not immediately ready to use. You can use the {@link describeIndex} function to check the status of the index. */ createIndex(options: CreateIndexOptions) { return this._createIndex(options); @@ -333,7 +396,7 @@ export class Pinecone { /** * Configure an index * - * Use this method to update configuration on an existing index. You can update the number of pods, replicas, and pod type. You can also update the metadata configuration. + * Use this method to update configuration on an existing index. You can update the number of replicas, and pod type. * * @example * ```js @@ -341,6 +404,7 @@ export class Pinecone { * ``` * * @param indexName - The name of the index to configure. + * @returns A promise that resolves to {@link IndexModel} when the request to configure the index is completed. * @param options - The configuration properties you would like to update */ configureIndex(indexName: IndexName, options: ConfigureIndexRequestSpecPod) { @@ -353,9 +417,10 @@ export class Pinecone { * @example * ```js * const indexList = await pinecone.listIndexes() + * const indexName = indexList.indexes[0].name; * await pinecone.createCollection({ * name: 'my-collection', - * source: indexList[0] + * source: indexName * }) * ``` * @@ -363,7 +428,7 @@ export class Pinecone { * @param options - The collection configuration. * @param options.name - The name of the collection. Must be unique within the project and contain alphanumeric and hyphen characters. The name must start and end with alphanumeric characters. * @param options.source - The name of the index to use as the source for the collection. - * @returns a promise that resolves when the request to create the collection is completed. + * @returns a promise that resolves to {@link CollectionModel} when the request to create the collection is completed. */ createCollection(options: CreateCollectionRequest) { return this._createCollection(options); @@ -377,7 +442,7 @@ export class Pinecone { * await pinecone.listCollections() * ``` * - * @returns A promise that resolves to an array of collection objects. + * @returns A promise that resolves to {@link CollectionList}. */ listCollections() { return this._listCollections(); @@ -389,7 +454,7 @@ export class Pinecone { * @example * ``` * const collectionList = await pinecone.listCollections() - * const collectionName = collectionList[0] + * const collectionName = collectionList.collections[0].name; * await pinecone.deleteCollection(collectionName) * ``` * @@ -409,7 +474,7 @@ export class Pinecone { * ``` * * @param collectionName - The name of the collection to describe. - * @returns A promise that resolves to a collection object with type {@link CollectionDescription}. + * @returns A promise that resolves to a {@link CollectionModel}. */ describeCollection(collectionName: CollectionName) { return this._describeCollection(collectionName); @@ -491,6 +556,7 @@ export class Pinecone { * * @typeParam T - The type of metadata associated with each record. * @param indexName - The name of the index to target. + * @param indexHostUrl - An optional host url to use for operations against this index. If not provided, the host url will be resolved by calling {@link describeIndex}. * @typeParam T - The type of the metadata object associated with each record. * @returns An {@link Index} object that can be used to perform data operations. */