Implement Namespaces API

.github/actions/external-app/edge/action.yml

@@ -1,5 +1,5 @@
 name: Spin up Vercel App
-
+description: 'Deploys the Vercel app and runs end-to-end tests against it'
 inputs:
   vercel-token:
     required: true
@@ -58,28 +58,9 @@ runs:
         vercel --token ${{ inputs.vercel-token }} --prod
       shell: bash
 
-    - name: Hit Vercel app endpoint(s) via assertResponse.ts file
-      run: |
-        npm install -g typescript
-        npm install -g ts-node
-        export PINECONE_API_KEY="${{ inputs.PINECONE_API_KEY }}"
-        ciUrl='https://ts-client-test-external-app.vercel.app/api/createSeedQuery'
-        indexName=$(ts-node ts-external-app-test/assertResponse.ts "$ciUrl" | grep "Index name:" | awk '{print $NF}' | tr -d '\r')
-        echo "indexName=$indexName" >> $GITHUB_ENV
-      shell: bash
-
-    - name: Clean up test index(es)
+    - name: Run end-to-end tests against the deployed Vercel app with assertResponse.ts
       run: |
-        PINECONE_API_KEY="${{ inputs.PINECONE_API_KEY }}"
-        matching_index="$indexName"
-
-        delete_response=$(curl -s -o /dev/null -w "%{http_code}" -X DELETE "https://api.pinecone.io/indexes/$matching_index" \
-        -H "Api-Key: $PINECONE_API_KEY")
-
-        if [ "$delete_response" -eq 202 ]; then
-          echo "Successfully deleted index: $matching_index"
-        else
-          echo "Failed to delete index: $matching_index. HTTP status code: $delete_response"
-          exit 1
-        fi
+        npx tsx ts-external-app-test/assertResponse.ts
+      env:
+        PINECONE_API_KEY: ${{ inputs.PINECONE_API_KEY }}
       shell: bash

README.md

@@ -642,7 +642,7 @@ const list = await pc.listCollections();
 
 ## Index operations
 
-Pinecone indexes support operations for working with vector data using operations such as upsert, query, fetch, and delete.
+Pinecone indexes support operations for working with vector data using methods such as upsert, query, fetch, and delete.
 
 ### Targeting an index
 
@@ -734,6 +734,25 @@ await index.fetch(['1']);
 
 See [Use namespaces](https://docs.pinecone.io/guides/indexes/use-namespaces) for more information.
 
+### Managing namespaces
+
+There are several operations for managing namespaces within an index. You can list the namespaces within an index, describe a specific namespace, or delete a namespace entirely.
+
+```typescript
+import { Pinecone } from '@pinecone-database/pinecone';
+const pc = new Pinecone();
+const index = pc.index('test-index');
+
+// list all namespaces
+const namespacesResp = await index.listNamespaces();
+
+// describe a namespace
+const namespace = await index.describeNamespace('ns1');
+
+// delete a namespace (including all record data)
+await index.deleteNamespace('ns1');
+```
+
 ### Upsert vectors
 
 Pinecone expects records inserted into indexes to have the following form:

src/control/__tests__/createIndexForModel.test.ts

@@ -9,7 +9,6 @@ import type {
   IndexModel,
 } from '../../pinecone-generated-ts-fetch/db_control';
 import { PineconeArgumentError } from '../../errors';
-import { waitUntilIndexIsReady } from '../createIndex';
 
 // describeIndexResponse can either be a single response, or an array of responses for testing polling scenarios
 const setupCreateIndexForModelResponse = (

src/data/__tests__/bulk/bulkOperationsProvider.test.ts

@@ -0,0 +1,84 @@
+import { BulkOperationsProvider } from '../../bulk/bulkOperationsProvider';
+import { IndexHostSingleton } from '../../indexHostSingleton';
+import { Configuration } from '../../../pinecone-generated-ts-fetch/db_data';
+
+jest.mock('../../../pinecone-generated-ts-fetch/db_data', () => ({
+  ...jest.requireActual('../../../pinecone-generated-ts-fetch/db_data'),
+  Configuration: jest.fn(),
+}));
+
+describe('BulkOperationsProvider', () => {
+  let real;
+  const config = {
+    apiKey: 'test-api-key',
+  };
+
+  beforeAll(() => {
+    real = IndexHostSingleton.getHostUrl;
+  });
+  afterAll(() => {
+    IndexHostSingleton.getHostUrl = real;
+  });
+  beforeEach(() => {
+    IndexHostSingleton.getHostUrl = jest.fn();
+  });
+  afterEach(() => {
+    IndexHostSingleton._reset();
+  });
+
+  test('makes no API calls on instantiation', async () => {
+    const config = {
+      apiKey: 'test-api-key',
+    };
+    new BulkOperationsProvider(config, 'index-name');
+    expect(IndexHostSingleton.getHostUrl).not.toHaveBeenCalled();
+  });
+
+  test('api calls occur only the first time the provide method is called', async () => {
+    const config = {
+      apiKey: 'test-api-key',
+    };
+    const provider = new BulkOperationsProvider(config, 'index-name');
+    expect(IndexHostSingleton.getHostUrl).not.toHaveBeenCalled();
+
+    const api = await provider.provide();
+    expect(IndexHostSingleton.getHostUrl).toHaveBeenCalled();
+
+    const api2 = await provider.provide();
+    expect(IndexHostSingleton.getHostUrl).toHaveBeenCalledTimes(1);
+    expect(api).toEqual(api2);
+  });
+
+  test('passing indexHostUrl skips hostUrl resolution', async () => {
+    const indexHostUrl = 'http://index-host-url';
+    const provider = new BulkOperationsProvider(
+      config,
+      'index-name',
+      indexHostUrl
+    );
+
+    jest.spyOn(provider, 'buildBulkOperationsConfig');
+
+    await provider.provide();
+
+    expect(IndexHostSingleton.getHostUrl).not.toHaveBeenCalled();
+    expect(provider.buildBulkOperationsConfig).toHaveBeenCalled();
+  });
+
+  test('passing additionalHeaders applies them to the API Configuration', async () => {
+    const additionalHeaders = { 'x-custom-header': 'custom-value' };
+    const provider = new BulkOperationsProvider(
+      config,
+      'index-name',
+      undefined,
+      additionalHeaders
+    );
+
+    await provider.provide();
+    expect(Configuration).toHaveBeenCalledWith(
+      expect.objectContaining({
+        headers: expect.objectContaining(additionalHeaders),
+      })
+    );
+  });
+});

src/data/__tests__/namespaces/namespacesOperationsProvider.test.ts

@@ -0,0 +1,84 @@
+import { NamespaceOperationsProvider } from '../../namespaces/namespacesOperationsProvider';
+import { IndexHostSingleton } from '../../indexHostSingleton';
+import { Configuration } from '../../../pinecone-generated-ts-fetch/db_data';
+
+jest.mock('../../../pinecone-generated-ts-fetch/db_data', () => ({
+  ...jest.requireActual('../../../pinecone-generated-ts-fetch/db_data'),
+  Configuration: jest.fn(),
+}));
+
+describe('NamespacesOperationsProvider', () => {
+  let real;
+  const config = {
+    apiKey: 'test-api-key',
+  };
+
+  beforeAll(() => {
+    real = IndexHostSingleton.getHostUrl;
+  });
+  afterAll(() => {
+    IndexHostSingleton.getHostUrl = real;
+  });
+  beforeEach(() => {
+    IndexHostSingleton.getHostUrl = jest.fn();
+  });
+  afterEach(() => {
+    IndexHostSingleton._reset();
+  });
+
+  test('makes no API calls on instantiation', async () => {
+    const config = {
+      apiKey: 'test-api-key',
+    };
+    new NamespaceOperationsProvider(config, 'index-name');
+    expect(IndexHostSingleton.getHostUrl).not.toHaveBeenCalled();
+  });
+
+  test('api calls occur only the first time the provide method is called', async () => {
+    const config = {
+      apiKey: 'test-api-key',
+    };
+    const provider = new NamespaceOperationsProvider(config, 'index-name');
+    expect(IndexHostSingleton.getHostUrl).not.toHaveBeenCalled();
+
+    const api = await provider.provide();
+    expect(IndexHostSingleton.getHostUrl).toHaveBeenCalled();
+
+    const api2 = await provider.provide();
+    expect(IndexHostSingleton.getHostUrl).toHaveBeenCalledTimes(1);
+    expect(api).toEqual(api2);
+  });
+
+  test('passing indexHostUrl skips hostUrl resolution', async () => {
+    const indexHostUrl = 'http://index-host-url';
+    const provider = new NamespaceOperationsProvider(
+      config,
+      'index-name',
+      indexHostUrl
+    );
+
+    jest.spyOn(provider, 'buildNamespaceOperationsConfig');
+
+    await provider.provide();
+
+    expect(IndexHostSingleton.getHostUrl).not.toHaveBeenCalled();
+    expect(provider.buildNamespaceOperationsConfig).toHaveBeenCalled();
+  });
+
+  test('passing additionalHeaders applies them to the API Configuration', async () => {
+    const additionalHeaders = { 'x-custom-header': 'custom-value' };
+    const provider = new NamespaceOperationsProvider(
+      config,
+      'index-name',
+      undefined,
+      additionalHeaders
+    );
+
+    await provider.provide();
+    expect(Configuration).toHaveBeenCalledWith(
+      expect.objectContaining({
+        headers: expect.objectContaining(additionalHeaders),
+      })
+    );
+  });
+});

src/data/index.ts

@@ -31,6 +31,10 @@ import { ListImportsCommand } from './bulk/listImports';
 import { DescribeImportCommand } from './bulk/describeImport';
 import { CancelImportCommand } from './bulk/cancelImport';
 import { BulkOperationsProvider } from './bulk/bulkOperationsProvider';
+import { NamespaceOperationsProvider } from './namespaces/namespacesOperationsProvider';
+import { listNamespaces } from './namespaces/listNamespaces';
+import { describeNamespace } from './namespaces/describeNamespace';
+import { deleteNamespace } from './namespaces/deleteNamespace';
 
 export type {
   PineconeConfiguration,
@@ -167,6 +171,12 @@ export class Index<T extends RecordMetadata = RecordMetadata> {
   private _describeImportCommand: DescribeImportCommand;
   /** @hidden */
   private _cancelImportCommand: CancelImportCommand;
+  /** @hidden */
+  private _listNamespacesCommand: ReturnType<typeof listNamespaces>;
+  /** @hidden */
+  private _describeNamespaceCommand: ReturnType<typeof describeNamespace>;
+  /** @hidden */
+  private _deleteNamespaceCommand: ReturnType<typeof deleteNamespace>;
 
   /** @internal */
   private config: PineconeConfiguration;
@@ -269,6 +279,17 @@ export class Index<T extends RecordMetadata = RecordMetadata> {
       bulkApiProvider,
       namespace
     );
+
+    // namespace operations
+    const namespaceApiProvider = new NamespaceOperationsProvider(
+      config,
+      indexName,
+      indexHostUrl,
+      additionalHeaders
+    );
+    this._listNamespacesCommand = listNamespaces(namespaceApiProvider);
+    this._describeNamespaceCommand = describeNamespace(namespaceApiProvider);
+    this._deleteNamespaceCommand = deleteNamespace(namespaceApiProvider);
   }
 
   /**
@@ -798,4 +819,66 @@ export class Index<T extends RecordMetadata = RecordMetadata> {
   async cancelImport(id: string) {
     return await this._cancelImportCommand.run(id);
   }
+
+  /**
+   * Returns a list of namespaces within the index.
+   *
+   * @example
+   * ```js
+   * import { Pinecone } from '@pinecone-database/pinecone';
+   * const pc = new Pinecone();
+   * const index = pc.index('my-serverless-index');
+   * console.log(await index.listNamespaces(10));
+   *
+   * // {
+   * //   namespaces: [
+   * //     { name: 'ns-1', recordCount: '1' },
+   * //     { name: 'ns-2', recordCount: '1' }
+   * //   ],
+   * //   pagination: undefined
+   * // }
+   * ```
+   *
+   * @param limit - (Optional) Max number of import operations to return per page.
+   * @param paginationToken - (Optional) Pagination token to continue a previous listing operation.
+   */
+  async listNamespaces(limit?: number, paginationToken?: string) {
+    return await this._listNamespacesCommand(limit, paginationToken);
+  }
+
+  /**
+   * Returns the details of a specific namespace.
+   *
+   * @example
+   * ```js
+   * import { Pinecone } from '@pinecone-database/pinecone';
+   * const pc = new Pinecone();
+   * const index = pc.index('my-serverless-index');
+   * console.log(await index.describeNamespace('ns-1'));
+   *
+   * // { name: 'ns-1', recordCount: '1' }
+   * ```
+   *
+   * @param namespace - The namespace to describe.
+   */
+  async describeNamespace(namespace: string) {
+    return await this._describeNamespaceCommand(namespace);
+  }
+
+  /**
+   * Deletes a specific namespace from the index, including all records within it.
+   *
+   * @example
+   * ```js
+   * import { Pinecone } from '@pinecone-database/pinecone';
+   * const pc = new Pinecone();
+   * const index = pc.index('my-serverless-index');
+   * await index.deleteNamespace('ns-1');
+   * ```
+   *
+   * @param namespace - The namespace to delete.
+   */
+  async deleteNamespace(namespace: string) {
+    return await this._deleteNamespaceCommand(namespace);
+  }
 }

src/data/namespaces/deleteNamespace.ts

@@ -0,0 +1,9 @@
+import { NamespaceOperationsProvider } from '../namespaces/namespacesOperationsProvider';
+
+export const deleteNamespace = (apiProvider: NamespaceOperationsProvider) => {
+  return async (namespace: string): Promise<void> => {
+    const api = await apiProvider.provide();
+    await api.deleteNamespace({ namespace });
+    return;
+  };
+};

src/data/namespaces/describeNamespace.ts

@@ -0,0 +1,9 @@
+import { NamespaceDescription } from '../../pinecone-generated-ts-fetch/db_data';
+import { NamespaceOperationsProvider } from '../namespaces/namespacesOperationsProvider';
+
+export const describeNamespace = (apiProvider: NamespaceOperationsProvider) => {
+  return async (namespace: string): Promise<NamespaceDescription> => {
+    const api = await apiProvider.provide();
+    return await api.describeNamespace({ namespace });
+  };
+};

src/data/namespaces/listNamespaces.ts

@@ -0,0 +1,12 @@
+import { ListNamespacesResponse } from '../../pinecone-generated-ts-fetch/db_data';
+import { NamespaceOperationsProvider } from '../namespaces/namespacesOperationsProvider';
+
+export const listNamespaces = (apiProvider: NamespaceOperationsProvider) => {
+  return async (
+    limit?: number,
+    paginationToken?: string
+  ): Promise<ListNamespacesResponse> => {
+    const api = await apiProvider.provide();
+    return await api.listNamespaces({ limit, paginationToken });
+  };
+};