pinecone_sdk/
lib.rs

1//! # Pinecone Rust SDK
2//!
3//! > ⚠️ **Warning:** This SDK is still in an alpha state. While it is mostly built out and functional,
4//! it may undergo changes as we continue to improve the UX. Please try it out and give us your feedback,
5//! but be aware that updates may introduce breaking changes.
6//!
7//! `pinecone-sdk` provides an interface for working with Pinecone services such as the Database and Inference APIs.
8//! See [docs.pinecone.io](https://docs.pinecone.io/) for more information.
9//!
10//! Before you can interact with Pinecone services, you'll need to create an account and generate an
11//! API key. This can be done through the Pinecone console: [https://app.pinecone.io](https://app.pinecone.io).
12//!
13//! ## Using the SDK
14//!
15//! The `PineconeClient` struct is the main point of entry into the Rust SDK.
16//! Parameters may either be directly passed through `PineconeClientConfig`, or read through environment variables:
17//!
18//! - (Required) The API key must be provided through `PineconeClientConfig.api_key`, or an environment variable named `PINECONE_API_KEY`.
19//!   If passed in as `None`, the client will attempt to read in an environment variable value, otherwise the passed value will be used.
20//! - (Optional) The control plane host, if passed in as `None`, will attempt to read in an environment variable called `PINECONE_CONTROLLER_HOST`.
21//!   If it is not an environment variable, it will default to `https://api.pinecone.io`.
22//!
23//! There are two ways of initializing a `PineconeClient`. The only required parameter for working with Pinecone is an API key:
24//!
25//! Use the `default_client()` function, which is the equivalent of constructing a `PineconeClientConfig` struct with all fields set to `None`.
26//! The API key will be read from environment variables
27//! ```no_run
28//! use pinecone_sdk::pinecone::PineconeClient;
29//! let client: PineconeClient = pinecone_sdk::pinecone::default_client().expect("Failed to create Pinecone instance");
30//! ```
31//!
32//! Initialize a `PineconeClientConfig` struct with parameters, and call `client()` to create a `PineconeClient` instance:
33//! ```no_run
34//! use pinecone_sdk::pinecone::{PineconeClient, PineconeClientConfig};
35//!
36//! let config = PineconeClientConfig {
37//!     api_key: Some("INSERT_API_KEY".to_string()),
38//!     ..Default::default()
39//! };
40//!
41//! let client: PineconeClient = config.client().expect("Failed to create Pinecone instance");
42//! ```
43//! Once you have a `PineconeClient` instance, you can use it to work with Pinecone services.
44//!
45//! ### Working with Indexes and Collections
46//!
47//! Indexes and collections can be managed with the `PineconeClient` instance directly.
48//!
49//! ```no_run
50//! use pinecone_sdk::pinecone;
51//! use pinecone_sdk::models::{Cloud, DeletionProtection, IndexModel, Metric, WaitPolicy};
52//! use pinecone_sdk::utils::errors::PineconeError;
53//! # async fn create_index_and_collection() -> Result<(), PineconeError> {
54//!     let client: pinecone::PineconeClient =
55//!     pinecone::default_client().expect("Failed to create PineconeClient");
56//!
57//!     let index: IndexModel = client
58//!         .create_serverless_index(
59//!             "my-index-name",
60//!             10,
61//!             Metric::Cosine,
62//!             Cloud::Aws,
63//!             "us-east-1",
64//!             DeletionProtection::Disabled,
65//!             WaitPolicy::NoWait,
66//!         )
67//!         .await?;
68//!
69//!     let collection = client.create_collection("my-collection-name", "my-previous-index-name").await?;
70//!
71//!     let index_description = client.describe_index("index-name").await?;
72//!     let collection_description = client.describe_collection("my-collection-name").await?;
73//!     let indexes = client.list_indexes().await?;
74//!
75//!     println!("Index description: {:?}", index_description);
76//!     println!("Collection description: {:?}", collection_description);
77//!     println!("Index list: {:?}", indexes);
78//!
79//! #   Ok(())
80//! # }
81//! ```
82//!
83//! ### Connecting to an Index
84//!
85//! Once you have an index created and you want to work with data, you will want to create an `Index` instance by using
86//! the `index()` method on the `PineconeClient` instance. You will need to provide the `host` of the index you are targeting
87//! which can be found by using the `describe_index()` or `list_indexes()` methods.
88//!
89//! ```no_run
90//! use pinecone_sdk::pinecone;
91//! use pinecone_sdk::models::{QueryResponse, Vector};
92//! use pinecone_sdk::utils::errors::PineconeError;
93//! # async fn upsert_and_query_vectors() -> Result<(), PineconeError> {
94//!     let client = pinecone::default_client().expect("Failed to initialize PineconeClient");
95//!     let index_description = client.describe_index("my-index").await?;
96//!     let mut index = client.index(&index_description.host).await?;
97//!
98//!     // upsert vectors
99//!     let vectors = [Vector {
100//!         id: "id1".to_string(),
101//!         values: vec![1.0, 2.0, 3.0, 4.0],
102//!         sparse_values: None,
103//!         metadata: None,
104//!     }, Vector {
105//!         id: "id2".to_string(),
106//!         values: vec![2.0, 3.0, 4.0, 5.0],
107//!         sparse_values: None,
108//!         metadata: None,
109//!     }];
110//!
111//!     let upsert_response = index.upsert(&vectors, &"my-namespace".into()).await?;
112//!     println!("Upserted {:?} vectors", upsert_response.upserted_count);
113//!
114//!     // query vectors
115//!     let query_vector = vec![1.0, 2.0, 3.0, 4.0];
116//!
117//!     let query_response: QueryResponse = index
118//!         .query_by_value(query_vector, None, 10, &"my-namespace".into(), None, None, None)
119//!         .await?;
120//!     println!("Query response: {:?}", query_response);
121//!
122//! #   Ok(())
123//! # }
124//! ```
125//!
126//! ### Working with Inference
127//!
128//! The Inference API is a service that gives you access to embedding models hosted on Pinecone's infrastructure.
129//! Read more at [Understanding Pinecone Inference](https://docs.pinecone.io/guides/inference/understanding-inference).
130//!
131//! ```
132//! use pinecone_sdk::pinecone;
133//! use pinecone_sdk::models::{EmbedRequestParameters};
134//! use pinecone_sdk::utils::errors::PineconeError;
135//! # async fn embed() -> Result<(), PineconeError> {
136//!     let client = pinecone::default_client().expect("Failed to initialize PineconeClient");
137//!     let embeddings = client
138//!     .embed(
139//!         "multilingual-e5-large",
140//!         Some(EmbedRequestParameters {
141//!             input_type: Some("passage".to_string()),
142//!             truncate: Some("END".to_string()),
143//!         }),
144//!         &vec![
145//!             "Turkey is a classic meat to eat at American Thanksgiving.",
146//!             "Many people enjoy the beautiful mosques in Turkey.",
147//!         ],
148//!     )
149//!     .await
150//!     .expect("Failed to embed");
151//!
152//!     println!("Embeddings: {:?}", embeddings);
153//! #    Ok(())
154//! # }
155//! ```
156//!
157//! For more detailed documentation on Pinecone see [https://docs.pinecone.io](https://docs.pinecone.io).
158
159#![warn(missing_docs)]
160
161/// Defines the main entrypoint of the Pinecone SDK.
162pub mod pinecone;
163
164/// Utility modules.
165pub mod utils;
166
167/// Models for the Pinecone SDK.
168pub mod models;
169
170/// Version information.
171pub mod version;
172
173/// OpenAPI client for Pinecone.
174#[allow(missing_docs)]
175#[allow(dead_code)]
176mod openapi;
177
178/// Protobuf client for Pinecone.
179#[allow(missing_docs)]
180#[allow(dead_code)]
181mod protos;
pinecone_sdk/lib.rs

pinecone_sdk/
lib.rs
