probots-io / pinecone-php

A beautiful, extendable PHP Package to communicate with your pinecone.io indices, collections and vectors.

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)

Pinecone Docs

$response = $pinecone->control()->index('my-index')->createPod(
    dimension: 1536,
    metric: 'cosine',
    podType: 'p1.x1',
    replicas: 1
    // ... more options    
);

if($response->successful()) {
    // 
}

Create Index (Serverless)

Pinecone Docs

$response = $pinecone->control()->index('my-index')->createServerless(
    dimension: 1536,
    metric: 'cosine',
    cloud: 'aws',
    region: 'us-west-2'
    // ... more options    
);

if($response->successful()) {
    // 
}

Describe Index

Pinecone Docs

$response = $pinecone->control()->index('my-index')->describe();

if($response->successful()) {
    // 
}

List Indices

Pinecone Docs

$response = $pinecone->control()->index()->list();

if($response->successful()) {
    // 
}

Configure Index

Pinecone Docs

$response = $pinecone->control()->index('my-index')->configure(
    pod_type: 'p1.x1',
    replicas: 1
);

if($response->successful()) {
    // 
}

Delete Index

Pinecone Docs

$response = $pinecone->control()->index('my-index')->delete();

if($response->successful()) {
    // 
}

Collection Operations

Work(s) with your collections too.

Create Collection

Pinecone Docs

$response = $pinecone->control()->collections('my-collection')->create(
    source: 'my-index'
);

if($response->successful()) {
    // 
}

Describe Collection

Pinecone Docs

$response = $pinecone->control()->collections('my-collection')->describe();

if($response->successful()) {
    // 
}

List Collections

Pinecone Docs

$response = $pinecone->control()->collections()->list();

if($response->successful()) {
    // 
}

Delete Collections

Pinecone Docs

$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

Pinecone Docs

$response = $pinecone->data()->vectors()->stats();

if($response->successful()) {
    // 
}

Update Vector

Pinecone Docs

$response = $pinecone->data()->vectors()->update(
    id: 'vector_1',
    values: array_fill(0, 128, 0.14),
    setMetadata: [
        'meta1' => 'value1',
    ]
);

if($response->successful()) {
    // 
}

Upsert Vectors

Pinecone Docs

$response = $pinecone->data()->vectors()->upsert(vectors: [
    'id' => 'vector_1',
    'values' => array_fill(0, 128, 0.14),
    'metadata' => [
        'meta1' => 'value1',
    ]
]);

if($response->successful()) {
    // 
}

Query Vectors

Pinecone Docs

$response = $pinecone->data()->vectors()->query(
    vector: array_fill(0, 128, 0.12),
    topK: 1,
);

if($response->successful()) {
    // 
}

Delete Vectors

Pinecone Docs

$response = $pinecone->data()->vectors()->delete(
    deleteAll: true
);

if($response->successful()) {
    // 
}

Fetch Vectors

Pinecone Docs

$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

• Marcus Pohorely
• All Contributors

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

pinecone-php's Issues

Support "List" endpoint - Query RAG documents by prefix

Is there plans for supporting Pinecone List endpoint for serverless indexes. This endpoint is crucial for Retrieval Augmented Generation (RAG) use cases, allowing us to query vector IDs using prefixes.

https://docs.pinecone.io/reference/list
https://docs.pinecone.io/docs/manage-rag-documents

Thanks for considering this addition and for this great package!

Can you create a release to reflect the saloonphp update?

As saloon has moved to saloonphp, can you create a release to reflect the commit from last year, please?

Gets rid of both of these warnings:

Package sammyjo20/saloon is abandoned, you should avoid using it. Use saloonphp/saloon instead.

Class Probots\Pinecone\Requests\Exceptions\MissingNameException located in ./vendor/probots-io/pinecone-php/src/Exceptions/MissingNameException.php does not comply with psr-4 autoloading standard. Skipping.

P.S - thanks for a great package!

Incorrect Query Parameter Formatting for Multiple IDs in Vector Fetching URL

The current implementation of the pinecone-php package constructs the URL for fetching vectors in a format that is not
compatible with the Pinecone API. The package generates a URL like this:

HOSTNAME/vectors/fetch?ids=vector-id-1,vector-id-2

However, the Pinecone API expects the URL to have multiple "ids" parameters, like this:

HOSTNAME/vectors/fetch?ids=vector-id-1&ids=vector-id-2

Note the ids=1&ids=2 , this is apparently valid and expected, news to me, not much we can do about it...