v2.0.0 Release

This release sees the introduction of the ability to create and manage serverless indexes. There are fundamental changes to control plane operations which include adjustments to function arguments and responses. See below for a summary of changes, and for a more detailed guide take a look at the v2-migration.md, the README.md, or the client reference.

Serverless indexes are currently in public preview, so make sure to review the current limitations and test thoroughly before using in production.

Changes overview

• Deploy Pinecone's new serverless indexes. The createIndex method has been refactored to accept an object conforming to the PodSpec or ServerlessSpec interfaces depending on how you would like to deploy your index. Many old properties such as podType, replicas, etc are moved into PodSpec since they do not apply to serverless indexes.
• Understand cost. The quantity of read units consumed by each serverless query and fetch call are now returned with the responses.
• Flexible API Keys. The v2.0.0 TypeScript SDK is consuming the new Control Plane API hosted at https://api.pinecone.io. This new API allows for a lot more flexibility in how API keys are used in comparison to the past when a rigid 1:1 relationship was enforced between projects and environments.
• Richer Responses. The listIndexes and listCollections methods now return an array with full descriptions of each resource, not merely an array of names. See here.
• Tidying up / Breaking changes
  • listIndexes now returns additional data, and the shape of the response has changed. See here.
  • listCollections now returns additional data, and the shape of the response has changed. See here.
  • describeIndex takes the same arguments as before (the index name), but returns data in a different shape reflecting the move of some configurations under the spec key and elevation of host to the top level. See a table of changed properties here.

Full Changelog: v1.1.3...v2.0.0

v1.1.3 Release

In this release we've updated the client reference documentation link in the README.md, and moved a number of non-runtime dependencies into devDependencies.

What's Changed

• Update README Reference Documentation link by @austin-denoble in #150
• Move non-runtime related deps to devDependencies by @SalmonMode in #175

New Contributors

• @SalmonMode made their first contribution in #175

Full Changelog: v1.1.2...v1.1.3

v1.1.2 Release

In this release we've included a fix for handling the global process object on certain edge platforms such as Cloudflare Workers. This should prevent runtime errors in environments where process is not available.

What's Changed

Fixes & troubleshooting

• Check for process existence before accessing it by @omarestrella in #147

Docs

• Fix styling in dark mode by @austin-denoble in #143
• [Docs] Update merge workflow to push generated artifacts to sdk-docs repo by @austin-denoble in #146

Testing & release

• [Fix] Expose environment vars in integration test cleanup job by @jhamon in #140

New Contributors

• @omarestrella made their first contribution in #147

Full Changelog: v1.1.1...v1.1.2

v1.1.1 Release

We are still working with some users to troubleshoot unexplained problems with the query method. These errors seem to be somehow related to a specific environment, dependency, or usage pattern because the have not been able to reproduce the query error in our integration testing and sample projects, including a nextjs project running on Vercel.

In this release, we have overhauled our error handling to fix a bug that caused the true underlyling error to be masked by an unrelated messaged (Cannot read properties of undefined (reading 'text')). We don't anticipate this will fully resolve the issue, but it will hopefully bring us closer to understanding the real problem.

We have also added an additional environment variable, PINECONE_DEBUG. When the client is run with PINECONE_DEBUG=true, all network calls will be logged out using console.debug by a request middleware.

What's Changed

Fixes & troubleshooting

• Overhaul error handling to prevent unrelated text() error from masking underlying exceptions by @jhamon in #135
• Add PINECONE_DEBUG request middleware by @jhamon in #136

Docs

• Add docs build and deploy to release-prod workflow by @austin-denoble in #127
• Refactoring for better typedoc output by @jhamon in #129
• [Docs] Update migration guide with notes on deprecated utils by @jhamon in #128
• Link reference docs in README by @jhamon in #130
• Fix typedoc Light/Dark mode styling by @austin-denoble in #133
• Add favicon to TypeDoc generated output via plugin script by @austin-denoble in #132

Testing & release

• Spruce release workflows by @jhamon in #131
• Add custom jest test reporters by @jhamon in #134
• Integration test cleanup workflow by @jhamon in #138
• Overhaul error handling to prevent unrelated text() error from masking underlying exceptions by @jhamon in #135

Full Changelog: v1.1.0...v1.1.1

v1.1.0 Release

Fixed: Next.js fetch compatibility

In this release we made some adjustments to how we polyfill fetch (which is not natively supported in all versions of node) to avoid conflicting with the Next.js framework. Next.js expects you to use @vercel/fetch and stubs out other polyfills to keep the bundle small, so the cross-fetch polyfill we depend on was not working as expected.

We have tested these changes in an updated version of our pinecone-vercel-starter sample app deployed on Vercel, so we think this resolves the known issues (#124) using the Pinecone TypeScript client in combination with Next.js.

If you encounter other problems with Vercel Edge Runtime or next.js, please file a new issue and we'll work on it ASAP. Smoothing out this experience is important to us.

Added: Replacements for some deprecated utilities

Following up on a conversation about v1 replacements for the deprecated utils methods waitUntilIndexIsReady and createIndexIfNotExists, you can now pass additional options to the create method.

import { Pinecone } from '@pinecone-database/pinecone';

const pinecone = new Pinecone()

await pinecone.createIndex({
  name: 'my-index',
  dimension: 1536,

  // This option tells the client not to throw if the index already exists.
  // It serves as replacement for createIndexIfNotExists
  suppressConflicts: true,

  // This option tells the client not to resolve the promise until the 
  // index is ready. It replaces waitUntilIndexIsReady.
  waitUntilReady: true
})

Changelog

Bug fixes

• [Bugfix] Implement next.js fetch compatibility by @jhamon in #126

Features

• Expose an option in createIndex to suppress the 409 conflict error by @glody007 in #125

Doc improvements

• Migration guide improvements by @jhamon in #120
• Add docstrings to Index class properties and methods by @austin-denoble in #123

Full Changelog: v1.0.1...v1.1.0

v1.0.1 Release

This fast-follow to last week's v1 release addresses a number of issues that have been reported by our users. Thank you to everyone who provided feedback.

Bugs addressed in this release

• #102 Typescript version-specific compilation problems
• #105 Configuration-specific conflicts with web types in lib.dom.d.ts
• #118 Some methods failing due to improper usage of the cross-fetch polyfill
• #108 Use of node libraries breaking Edge Runtime

In particular, I think we significantly underestimated how brittle the TypeScript ecosystem is and should have done more compatibility testing ahead of release. We've now added automated compilation testing across a matrix of TypeScript versions which gives us confidence we've caught the most common problems.

Special thanks to:

• @liljohnak for providing an executable minimum reproduction case for some of the TypeScript compilation errors. This formed the initial basis of the automated checks we've added in CI.
• @RickRyan26 for helping us test a dev build addressing the Edge Runtime issues.
• @glody007 for contributing docs fixes

PRs in this release

• #114 Resolves numerous TypeScript compilation problems and add CI checks to ensure continued TypeScript version compatibility.
• #107 Discontinued use of @sinclair/typebox Static due to potential for contributing to TypeScript compilation problems
• #115 and #110 address the Edge Runtime use case. We've removed node dependencies that were conflicting and added an integration test run using the @edge-runtime/jest-environment environment to help us avoid future problems.
• #119 Adds a few missing type exports
• #109 Makes adjustments to our use of cross-fetch polyfill
• #116 Additional integration testing with the semantic-search example app
• #104, #113 Documentation fixes

New Contributors

• @glody007 made their first contribution in #104
• @zackproser made their first contribution in #113

Full Changelog: v1.0.0...v1.0.1

v1.0.0 Release

This release adds a new module export, Pinecone, that is an all-new client for calling Pinecone from your TypeScript applications.

See the README docs and Migration guide to get started.

Features in this release

• Simplified library initialization. Now you can simply new Pinecone() to make a client instance without the need for any awkward async initialization steps. The new client can also read the PINECONE_ENVIRONMENT and PINECONE_API_KEY environment variables in lieu of a config argument.

import { Pinecone, PineconeClient } from '@pinecone-database/pinecone'

const config = { apiKey: 'your-api-key', environment: 'your-environment' }

// Legacy client had this awkward 2-step init
const pineconeClient = new PineconeClient(); 
await pineconeClient.init(config);

// New client is a normal object with no extra steps needed
const pinecone = new Pinecone(config);

• Simplified method signatures. The legacy client was generated using openapi and contained a lot of top-level keys in method parameters that were confusing and cumbersome to use. Now we have streamlined things across the board to eliminate these useless top-level keys.

// Old client
const pineconeClient = new PineconeClient(); 
await pineconeClient.init(config);
await pineconeClient.createIndex({ createRequest: { name: 'my-index', dimension: 1536 }})

// New client
const pinecone = new Pinecone()
await pinecone.createIndex({ name: 'my-index', dimension: 1536 })

• Easily target namespaces. For those using paid indexes, namespaces are a useful way to organize your data but in the legacy client using them required passing the namespace with every request. That was error-prone and led to confusing results if the namespace param was ever accidentally omitted. Now you can specify namespace once to create a scoped client instance that will send all operations to the same namespace.

const vectors = [...] // Assume you have some embeddings to upsert
const queryVector = [...] // and also a query embedding

// The legacy PineconeClient required passing namespace in every method call. 
// This made the code verbose and error prone.
const pineconeClient = new PineconeClient();
await pineconeClient.init(config);
const index = pineconeClient.index('index-name') 
await index.upsert({ 
 upsertRequest: 
   { 
     vectors, 
     namespace: 'ns1' 
   }
})
const results = await index.query({ 
 queryRequest: { 
   topK: 2, 
   vector: queryVector, 
   namespace: 'ns1' // don't forget this, or else!
 }
})

// The new Pinecone client can create a scoped index client that accepts data 
// operations without the need to pass namespace with every method call.
const pinecone = new Pinecone();
const ns1 = pinecone.index('index-name').namespace('ns1'); 
await ns1.upsert(vectors)
const results2 = await ns1.query({ topK: 2, vector: queryVector })

• Published TypeScript types with support for generics to enable proper typing of metadata. Say goodbye to awkward type casting every time you want to access information in metadata.

const pinecone = new Pinecone()

// User-defined type for metadata
type MovieMetadata = {
  title: string,
  genre: string,
  runtime: number
}

// You can now tell the client what type you expect metadata to have
// so you won't have to cast the type of query or fetch results.
const index = pinecone.index<MovieMetadata>('movie-embeddings')

const response = index.fetch(['1234'])
const movieRecord = response.records['1234']
if (movieRecord && movieRecord.metadata) {
  // Now typescript should no longer require any casting to interact with this metadata
  console.log(movieRecord.metadata.genre)
}

// And if you pass the wrong metadata into upsert you should now get typescript feedback
await index.upsert([{ 
  id: '2345', 
  values: [0.2, 0.3, 0.4], 
  metadata: { description: 'this prop not in MovieMetadata' } // should be ts error
}])

• Runtime validations to give improved user feedback and stacktraces when incorrect parameters are passed to the library. These validations can be disabled if desired by setting PINECONE_DISABLE_RUNTIME_VALIDATIONS=true

> await pinecone.createIndex({ name: 'test-index' })
Uncaught:
PineconeArgumentError: The argument to createIndex must have required property: dimension.
    at /Users/jhamon/workspace/pinecone-ts-client/dist/validator.js:201:19
    at /Users/jhamon/workspace/pinecone-ts-client/dist/control/createIndex.js:64:21
    at step (/Users/jhamon/workspace/pinecone-ts-client/dist/control/createIndex.js:33:23)
    at Object.next (/Users/jhamon/workspace/pinecone-ts-client/dist/control/createIndex.js:14:53)
    at /Users/jhamon/workspace/pinecone-ts-client/dist/control/createIndex.js:8:71
    at new Promise (<anonymous>)
    at __awaiter (/Users/jhamon/workspace/pinecone-ts-client/dist/control/createIndex.js:4:12)
    at Pinecone.createIndex (/Users/jhamon/workspace/pinecone-ts-client/dist/control/createIndex.js:59:40)
    at REPL18:1:48

• Backwards compatible. Since all these changes are implemented as part of a new Pinecone client export, if you have production code using the legacy PineconeClient export you can continue to use it without changes for now. But we hope you will gradually migrate to the Pinecone client because the PineconeClient will be removed in a future release.
• Migration to the Apache 2 open source license. This library was previously release under another permissive open source license (MIT license) so this will be a distinction without a difference for most users. But this is the first step we're taking toward standardizing all of our published client code on one open source license.
• Other convenience methods and improvements:
  • Delete more easily using deleteOne, deleteMany, and deleteAll.
  • Need to upsert data immediately after creating an index? The waitUntilReady parameter tells the create method not to resolve the promise until an index is ready to receive data. await pinecone.createIndex({ name: 'name', dimension: 10, waitUntilReady: true })

Documentation and Examples

• The update README shows usage
• See the Migration Guide for more examples on how to update legacy PineconeClient usage to the new Pinecone client export
• Check out example apps
  • Semantic search
  • Article recommender
  • Image search

0.1.5 (May 9, 2023)

Fixes

• Remove process.nextTick() to fix error in edge runtime #44