Pinecone Rust SDK

⚠️ Warning: This SDK is still in an alpha state. While it is mostly built out and functional, it may undergo changes as we continue to improve the UX. Please try it out and give us your feedback, but be aware that updates may introduce breaking changes.

Documentation

The documentation can be found here.

Prerequisites

Rust version: tested with Rust version 1.78.0

Before you can use the Pinecone SDK, you must sign up for an account and find your API key in the Pinecone console dashboard at https://app.pinecone.io.

Installation

Run cargo add pinecone-sdk to add the crate as a dependency, or add the line pinecone-sdk = "0.1.2" to your Cargo.toml file under [dependencies]. More on the crate can be found here.

Usage

The PineconeClient class is the main point of entry into the Rust SDK. Parameters may either be directly passed in as Options, or read through environment variables as follows. More detail:

• The API key must be passed in either as an argument or as an environment variable called PINECONE_API_KEY. If passed in as None, the client will attempt to read in an environment variable value.
• The control plane host, if passed in as None, will attempt to read in an environment variable called PINECONE_CONTROLLER_HOST. If it is not an environment variable, it will default to https://api.pinecone.io.

There are a couple of ways to instantiate the client, detailed below:

PineconeClientConfig

Initialize a PineconeClientConfig struct with parameters, and call config using the struct.

use pinecone_sdk::pinecone::{PineconeClient, PineconeClientConfig};

let config = PineconeClientConfig {
    api_key: Some("INSERT_API_KEY".to_string()),
    control_plane_host: Some("INSERT_CONTROLLER_HOST".to_string()),
    ..Default::default()
};

let pinecone: PineconeClient = config.client().expect("Failed to create Pinecone instance");

Default client

Use the default_client() function, which is the equivalent of constructing a PineconeClientConfig struct with all fields set to None. The API key and control plane host (optional) will be read from environment variables.

let pinecone: PineconeClient = pinecone_sdk::pinecone::default_client().expect("Failed to create Pinecone instance");

Indexes

Create Index

Create serverless index

The following example creates a serverless index in the us-east-1 region of AWS. For more information on serverless and regional availability, see Understanding indexes

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::models::{Metric, Cloud, WaitPolicy, IndexModel};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let index_description: IndexModel = pinecone.create_serverless_index(
    "index-name",       // Name of the index
    10,                 // Dimension of the vectors
    Metric::Cosine,     // Distance metric
    Cloud::Aws,         // Cloud provider
    "us-east-1",        // Region
    WaitPolicy::NoWait  // Timeout
).await?;

Create pod index

The following example creates a pod index in the us-east-1 region of AWS.

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::models::{Metric, Cloud, WaitPolicy, IndexModel};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let index_description: IndexModel = pinecone.create_pod_index(
    "index-name",       // Index name
    10,                 // Dimension
    Metric::Cosine,     // Distance metric
    "us-east-1",        // Region
    "p1.x1",            // Pod type
    1,                  // Number of pods
    None,               // Number of replicas
    None,               // Number of shards
    None,               // Metadata to index
    None,               // Source collection
    WaitPolicy::NoWait  // Wait policy
).await?;

Pod indexes support several optional configuration fields. The following example constructs a pod index with some specification for these fields.

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::models::{Metric, Cloud, WaitPolicy, IndexModel};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let index_description: IndexModel = pinecone.create_pod_index(
    "index-name",       // Index name
    10,                 // Dimension
    Metric::Cosine,     // Distance metric
    "us-east-1",        // Region
    "p1.x1",            // Pod type
    1,                  // Number of pods
    Some(1),            // Number of replicas
    Some(1),            // Number of shards
    Some(               // Metadata fields to index
        &vec!["genre",
            "title",
            "imdb_rating"]),
    Some("collection"), // Source collection
    WaitPolicy::NoWait  // Wait policy
).await?;

List indexes

The following example lists all indexes in your project.

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::models::IndexList;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let index_list: IndexList = pinecone.list_indexes().await?;

Describe index

The following example returns information about the index index-name.

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::models::IndexModel;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let index_description: IndexModel = pinecone.describe_index("index-name").await?;

Configure index

Configuring an index takes in three optional parameters -- a DeletionProtection enum, the number of replicas, and the pod type. The deletion protection can be updated for any index type, while the number of replicas and the pod type can only be updated for pod indexes.

The following example disables deletion protection for the index index-name.

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::models::IndexModel;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let index_description: IndexModel = pinecone.configure_index("index-name", Some(DeletionProtection::Disabled), None, None).await?;

The following example changes the index index-name to have 6 replicas and pod type s1. The deletion protection type will not be changed in this case.

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::models::IndexModel;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let index_description: IndexModel = pinecone.configure_index("index-name", None, Some(6), Some("s1")).await?;

Delete index

The following example deletes the index index-name.

use pinecone_sdk::pinecone::PineconeClientConfig;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

pinecone.delete_index("index-name").await?;

Describe index statistics

The following example returns statistics about the index with host index-host. Without filter

use std::collections::BTreeMap;
use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::models::DescribeIndexStatsResponse;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let mut index = pinecone.index("index-host").await?;

let response: DescribeIndexStatsResponse = index.describe_index_stats(None).await?;

With filter

use std::collections::BTreeMap;
use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::models::{Value, Kind, Metadata, DescribeIndexStatsResponse};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let mut index = pinecone.index("index-host").await?;

let mut fields = BTreeMap::new();
let kind = Some(Kind::StringValue("value".to_string()));
fields.insert("field".to_string(), Value { kind });

let response: DescribeIndexStatsResponse = index.describe_index_stats(Some(Metadata { fields })).await?;

Upsert vectors

The following example upserts two vectors into the index with host index-host.

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::models::{Vector, UpsertResponse};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let mut index = pinecone.index("index-host").await?;

let vectors = [Vector {
    id: "id1".to_string(),
    values: vec![1.0, 2.0, 3.0, 4.0],
    sparse_values: None,
    metadata: None,
}, Vector {
    id: "id2".to_string(),
    values: vec![2.0, 3.0, 4.0, 5.0],
    sparse_values: None,
    metadata: None,
}];

let response: UpsertResponse = index.upsert(&vectors, &"namespace".into()).await?;

Query vectors

There are two supported ways of querying an index.

Query by index

The following example queries the index with host index-host for the vector with ID vector-id, and returns the top 10 matches.

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::models::{Namespace, QueryResponse};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

// Connect to index at host "index-host"
let mut index = pinecone.index("index-host").await?;

// Query the vector with id "vector-id" in the namespace "namespace"
let response: QueryResponse = index.query_by_id(
    "vector-id".to_string(),
    10,
    &Namespace::default(),
    None,
    None,
    None
).await?;

Query by value

The following example queries the index with host index-host for the vector with values [1.0, 2.0, 3.0, 4.0], and returns the top 10 matches.

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::models::{Namespace, QueryResponse};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let mut index = pinecone.index("index-host").await?;

let vector = vec![1.0, 2.0, 3.0, 4.0];

let response: QueryResponse = index.query_by_value(
    vector,
    None,
    10,
    &Namespace::default(),
    None,
    None,
    None
).await?;

Delete vectors

There are three supported ways of deleting vectors.

Delete by ID

The following example deletes the vector with ID vector-id in the namespace namespace.

use pinecone_sdk::pinecone::PineconeClientConfig;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let mut index = pinecone.index("index-host").await?;

let ids = ["vector-id"]

index.delete_by_id(&ids, &"namespace".into()).await?;

Delete by filter:

The following example deletes vectors that satisfy the filter in the namespace namespace.

use std::collections::BTreeMap;
use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::models::{Metadata, Value, Kind, Namespace};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let mut fields = BTreeMap::new();
let kind = Some(Kind::StringValue("value".to_string()));
fields.insert("field".to_string(), Value { kind });

index.delete_by_filter(Metadata { fields }, &"namespace".into()).await?;

Delete all:

The following example deletes all vectors in the namespace namespace.

use pinecone_sdk::pinecone::PineconeClientConfig;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let mut index = pinecone.index("index-host").await?;

index.delete_all(&"namespace".into()).await?;

Fetch vectors

The following example fetches the vectors with IDs 1 and 2 from the default namespace.

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::models::FetchResponse;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let mut index = pinecone.index("index-host").await?;

let vectors = &["1", "2"];

let response: FetchResponse = index.fetch(vectors, &Default::default()).await?;

Update vectors

The following example updates the vector with ID vector-id in the namespace namespace to have values [1.0, 2.0, 3.0, 4.0].

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::models::UpdateResponse;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let mut index = pinecone.index("index-host").await?;

let response: UpdateResponse = index.update("vector-id", vec![1.0, 2.0, 3.0, 4.0], None, None, &"namespace".into()).await?;

List vectors

The following example lists vectors in the namespace namespace.

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::models::{Namespace, ListResponse};

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let mut index = pinecone.index("index-host").await?;

let response: ListResponse = index.list(&"namespace".into(), None, None, None).await?;

Collections

Create collection

The following example creates a collection collection-name in the index index-name.

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::models::CollectionModel;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let collection: CollectionModel = pinecone.create_collection("collection-name", "index-name").await?;

List collections

The following example lists all collections in a project.

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::models::CollectionList;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let collection_list: CollectionList = pinecone.list_collections().await?;

Describe collection

The following example describes the collection collection-name.

use pinecone_sdk::pinecone::PineconeClientConfig;
use pinecone_sdk::models::CollectionModel;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

let collection: CollectionModel = pinecone.describe_collection("collection-name").await?;

Delete collection

The following example deletes the collection collection-name.

use pinecone_sdk::pinecone::PineconeClientConfig;

let config = PineconeClientConfig {
    api_key: Some('<<PINECONE_API_KEY>>'),
    ..Default::default()
};
let pinecone = config.client()?;

pinecone.delete_collection("collection-name").await?;

Contributing

If you'd like to make a contribution, or get setup locally to develop the Pinecone Rust client, please see our contributing guide