3 releases
0.1.2 | Sep 6, 2024 |
---|---|
0.1.1 | Aug 7, 2024 |
0.1.0 | Aug 7, 2024 |
#1016 in Database interfaces
6,343 downloads per month
325KB
5.5K
SLoC
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 asNone
, 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 calledPINECONE_CONTROLLER_HOST
. If it is not an environment variable, it will default tohttps://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
Dependencies
~13–26MB
~377K SLoC