Awesome
Pinecone PHP
A beautiful, extendable PHP Package to communicate with your pinecone.io indices, collections and vectors, powered by Saloon.
Info From Version 1.x onwards we are using the latest Pinecone API which support serverless. If you need the legacy API please use a version before 1.0.0!
Introduction
This API provides a feature rich, elegant baseline for working with the pinecone.io API. Developers can install and leverage this API to help them integrate pinecone.io easily and beautifully.
Installation
composer require probots-io/pinecone-php
Features
Currently supports all of the available endpoints in the pinecone.io API based on the official documentation
Authentication
Authentication via Api Key is the only available authentication methods currently supported. First, you will need to create an Api Key in your pinecone.io instance.
use \Probots\Pinecone\Client as Pinecone;
$apiKey = 'YOUR_PINECONE_API_KEY';
// Initialize Pinecone
$pinecone = new Pinecone($apiKey);
// Now you are ready to make requests, all requests will be authenticated automatically.
Quick Start
There are two ways to initialize the SDK. You can either provide an index during initialization or you can provide it later on.
use \Probots\Pinecone\Client as Pinecone;
$apiKey = 'YOUR_PINECONE_API_KEY';
$pinecone = new Pinecone($apiKey);
// all control methods are available now, create an index or similar
// e.g. $pinecone->control()->index()
// later on you can provide the index
$pinecone->setIndexHost('INDEX_HOST_FROM_PINECONE');
// data methods are available now
// e.g. $pinecone->data()->vectors()
or
use \Probots\Pinecone\Client as Pinecone;
$apiKey = 'YOUR_PINECONE_API_KEY';
$indexHost = 'INDEX_HOST_FROM_PINECONE';
$pinecone = new Pinecone($apiKey, $indexHost);
// all control AND data methods are available now
Info The index host should include
https://
, which you may need to prepend to the value returned from Pinecone.
Responses
All responses are returned as a Response
object.
Please check the Saloon documentation to see all
available methods.
Control Pane
Index Operations
Work(s) with your indices.
Create Index (POD)
$response = $pinecone->control()->index('my-index')->createPod(
dimension: 1536,
metric: 'cosine',
podType: 'p1.x1',
replicas: 1
// ... more options
);
if($response->successful()) {
//
}
Create Index (Serverless)
$response = $pinecone->control()->index('my-index')->createServerless(
dimension: 1536,
metric: 'cosine',
cloud: 'aws',
region: 'us-west-2'
// ... more options
);
if($response->successful()) {
//
}
Describe Index
$response = $pinecone->control()->index('my-index')->describe();
if($response->successful()) {
//
}
List Indices
$response = $pinecone->control()->index()->list();
if($response->successful()) {
//
}
Configure Index
$response = $pinecone->control()->index('my-index')->configure(
pod_type: 'p1.x1',
replicas: 1
);
if($response->successful()) {
//
}
Delete Index
$response = $pinecone->control()->index('my-index')->delete();
if($response->successful()) {
//
}
Collection Operations
Work(s) with your collections too.
Create Collection
$response = $pinecone->control()->collections('my-collection')->create(
source: 'my-index'
);
if($response->successful()) {
//
}
Describe Collection
$response = $pinecone->control()->collections('my-collection')->describe();
if($response->successful()) {
//
}
List Collections
$response = $pinecone->control()->collections()->list();
if($response->successful()) {
//
}
Delete Collections
$response = $pinecone->control()->collections('my-collection')->delete();
if($response->successful()) {
//
}
Data Pane
Info These operations need the index to be set. You can set the index during initialization or later on. See description at the beginning.
Vector Operations
Vectors are the basic unit of data in Pinecone. Use them.
Get Index Stats
$response = $pinecone->data()->vectors()->stats();
if($response->successful()) {
//
}
Update Vector
$response = $pinecone->data()->vectors()->update(
id: 'vector_1',
values: array_fill(0, 128, 0.14),
setMetadata: [
'meta1' => 'value1',
]
);
if($response->successful()) {
//
}
Upsert Vectors
$response = $pinecone->data()->vectors()->upsert(vectors: [
'id' => 'vector_1',
'values' => array_fill(0, 128, 0.14),
'metadata' => [
'meta1' => 'value1',
]
]);
if($response->successful()) {
//
}
Query Vectors
$response = $pinecone->data()->vectors()->query(
vector: array_fill(0, 128, 0.12),
topK: 1,
);
if($response->successful()) {
//
}
Delete Vectors
$response = $pinecone->data()->vectors()->delete(
deleteAll: true
);
if($response->successful()) {
//
}
Fetch Vectors
$response = $pinecone->data()->vectors()->fetch([
'vector_1', 'vector_2'
]);
if($response->successful()) {
//
}
Testing
Testing is done via PestPHP. You can run the tests by running ./vendor/bin/pest
in the root of the project.
Copy .env.example to .env and update accordingly.
Credits
License
The MIT License (MIT). Please see License File for more information.
TODO - Submit PR if you want to contribute:
- validate parameters based on API docs - needs more checking
- Implement Custom Exceptions
- Add failure tests
- Add some examples
- Finish docs