### Install @upstash/vector using npm or pnpm

Source: https://upstash.com/docs/vector/sdks/ts/getting-started

This snippet shows how to install the @upstash/vector SDK using either npm or pnpm package managers. Ensure you have Node.js and npm/pnpm installed.

```shell
npm install @upstash/vector
```

```shell
pnpm add @upstash/vector
```

--------------------------------

### Install Upstash Vector PHP SDK using Composer

Source: https://upstash.com/docs/vector/sdks/php/getting-started

This command installs the Upstash Vector PHP SDK using Composer, the dependency manager for PHP. Ensure Composer is installed globally on your system.

```shell
composer require upstash/vector
```

--------------------------------

### Install Upstash Vector SDK for Python

Source: https://upstash.com/docs/vector/sdks/py/gettingstarted

Install the upstash-vector Python SDK using pip. This command fetches and installs the latest version of the library from the Python Package Index (PyPI).

```bash
pip install upstash-vector
```

--------------------------------

### Install upstash/vector-laravel SDK

Source: https://upstash.com/docs/vector/sdks/php/laravel

This command installs the Upstash Vector Laravel SDK using Composer. Ensure you have Composer installed and configured for your Laravel project.

```shell
composer require upstash/vector-laravel
```

--------------------------------

### Initialize Upstash Vector Client with Environment Variables

Source: https://upstash.com/docs/vector/sdks/ts/getting-started

Demonstrates initializing the Upstash Vector client using environment variables. The client automatically picks up `UPSTASH_VECTOR_REST_URL` and `UPSTASH_VECTOR_REST_TOKEN` if set.

```typescript
import { Index } from "@upstash/vector";

const index = new Index();
```

--------------------------------

### Upsert Vector with Metadata using Upstash Vector SDK (Python)

Source: https://upstash.com/docs/vector/sdks/py/gettingstarted

Example of using the upstash-vector SDK in Python to upsert a vector into the index. This snippet demonstrates generating a random vector, defining associated metadata, and calling the `upsert` method. It assumes the Index client has been initialized using environment variables.

```python
import random
from upstash_vector import Index

# Initialize the index client using environment variables
index = Index.from_env()

def main():
    # Define the dimension based on the index configuration
    dimension = 128
    # Generate a random vector for upsert
    vector_to_upsert = [random.random() for _ in range(dimension)]
    # Additional metadata associated with the vector
    metadata = {"text": "example test for metadata"}

    # Upsert the vector into the index
    index.upsert(vectors=[
        ("id-for-vector", vector_to_upsert, metadata)
    ])

```

--------------------------------

### Set Upstash Vector Credentials via Environment Variables

Source: https://upstash.com/docs/vector/sdks/php/getting-started

Sets the environment variables required for the Upstash Vector client to connect to the REST API. Replace placeholders with your actual credentials.

```bash
UPSTASH_VECTOR_REST_URL="your_rest_url"
UPSTASH_VECTOR_REST_TOKEN="your_rest_token"
```

--------------------------------

### Initialize Upstash Vector Client with Configuration Object

Source: https://upstash.com/docs/vector/sdks/ts/getting-started

Shows how to initialize the Upstash Vector client by providing the REST URL and token directly in a configuration object. This is useful for managing multiple project configurations.

```typescript
import { Index } from "@upstash/vector";

const index = new Index({
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
});
```

--------------------------------

### Manually Initialize Upstash Vector Client

Source: https://upstash.com/docs/vector/sdks/php/getting-started

Manually initializes the Upstash Vector client by passing the REST URL and Token directly to the constructor. This method is useful for managing multiple configurations.

```php
use Upstash\Vector\Index;

$index = new Index(
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
);
```

--------------------------------

### Initialize Upstash Vector Client from Environment Variables

Source: https://upstash.com/docs/vector/sdks/php/getting-started

Initializes the Upstash Vector client by reading REST URL and Token from environment variables UPSTASH_VECTOR_REST_URL and UPSTASH_VECTOR_REST_TOKEN. Ensure these variables are set before execution.

```php
use Upstash\Vector\Index;

$index = Index::fromEnv();
```

--------------------------------

### Publish and Configure Upstash Vector Package

Source: https://upstash.com/docs/vector/sdks/php/laravel

This command publishes the configuration file for the upstash/vector-laravel package, allowing you to customize settings, such as defining multiple index connections. The configuration file will be located at `config/vector.php`.

```shell
php artisan vendor:publish --tag="vector-config"
```

--------------------------------

### Initialize Upstash Vector Index Client (Python)

Source: https://upstash.com/docs/vector/sdks/py/gettingstarted

Initialize the Upstash Vector Index client in Python. You can either provide the URL and token directly or use the `from_env()` class method to load credentials from environment variables, which is recommended for serverless environments.

```python
from upstash_vector import Index
index = Index(url="UPSTASH_VECTOR_REST_URL", token="UPSTASH_VECTOR_REST_TOKEN")
```

```python
from upstash_vector import Index
index = Index.from_env()
```

--------------------------------

### Upsert Data

Source: https://upstash.com/docs/vector/api/get-started

This endpoint allows you to upsert data into your Upstash Vector database. It requires an ID and the vector data. Authentication is handled via a bearer token.

```APIDOC
## POST /upsert

### Description
Upserts a vector into the database. If a vector with the given ID already exists, it will be overwritten.

### Method
POST

### Endpoint
/upsert

### Parameters
#### Query Parameters
None

#### Request Body
- **id** (string) - Required - The unique identifier for the vector.
- **vector** (array of numbers) - Required - The vector data, represented as an array of numbers.

### Request Example
```json
{
  "id": "id-0",
  "vector": [0.87, 0.99]
}
```

### Response
#### Success Response (200)
- **result** (string) - Indicates the success of the operation. Example: "Success"

#### Response Example
```json
{ "result": "Success" }
```

#### Error Response
- **error** (string) - Description of the error. Example: "Unauthorized: Invalid auth token"
- **status** (number) - The HTTP status code of the error. Example: 401

#### Error Response Example
```json
{
  "error": "Unauthorized: Invalid auth token",
  "status": 401
}
```

#### HTTP Response Codes
- **200 OK**: Request accepted and successfully executed.
- **400 Bad Request**: Syntax error, invalid/unsupported command, or command execution failure.
- **401 Unauthorized**: Authentication failed (missing or invalid auth token).
- **405 Method Not Allowed**: Unsupported HTTP method used. Only HEAD, GET, POST, and PUT are allowed.
```

--------------------------------

### Define Command-Level Metadata Type for Specific Operations

Source: https://upstash.com/docs/vector/sdks/ts/getting-started

Demonstrates how to specify a metadata type for a particular command, like `upsert`, without setting it at the index level. This provides flexibility when different commands require different metadata structures.

```typescript
import { Index } from "@upstash/vector";

type Metadata = { genre: string, year: number };

const index = new Index();

index.upsert<Metadata>({ id: 1, vector: [...], metadata: { 
  genre: "comedy",
  year: 1990
}});
```

--------------------------------

### Configure Multiple Upstash Vector Connections

Source: https://upstash.com/docs/vector/sdks/php/laravel

This configuration example shows how to set up multiple Upstash Vector connections in your Laravel application. Each connection can have its own URL and token, defined by different environment variables.

```php
return [
    'default' => env('UPSTASH_VECTOR_CONNECTION', 'default'),

    'connections' => [
        'default' => [
            'url' => env('UPSTASH_VECTOR_REST_URL'),
            'token' => env('UPSTASH_VECTOR_REST_TOKEN'),
        ],
        'another' => [
            'url' => env('SECOND_UPSTASH_VECTOR_REST_URL'),
            'token' => env('SECOND_UPSTASH_VECTOR_REST_TOKEN'),
        ],
    ],
];
```

--------------------------------

### Install Bun Package Manager

Source: https://upstash.com/docs/vector/sdks/ts/contributing

Installs the Bun JavaScript runtime, which is used for packaging and dependency management in this project. This command fetches and executes the installation script for Bun.

```commandline
curl -fsSL https://bun.sh/install | bash
```

--------------------------------

### Python Full Index Scan Example

Source: https://upstash.com/docs/vector/sdks/py/example_calls/range

Illustrates how to scan the entire index by iteratively calling the 'range' method. It starts with an initial query and continues fetching results using the `next_cursor` until all vectors are retrieved.

```python
res = index.range(cursor="", limit=5)
print(res.vectors)

while res.next_cursor != "":
    res = index.range(cursor=res.next_cursor, limit=10)
    print(res.vectors)
```

--------------------------------

### Handle successful REST API response

Source: https://upstash.com/docs/vector/api/get-started

This snippet shows the expected JSON response from the Upstash Vector REST API when a command is executed successfully. A successful response includes a 'result' field indicating 'Success'.

```json
{ "result": "Success" }
```

--------------------------------

### Define Index-Level Metadata Type for Type Safety

Source: https://upstash.com/docs/vector/sdks/ts/getting-started

Illustrates how to define a TypeScript type for metadata at the index level, ensuring type safety for operations like query, upsert, fetch, and range.

```typescript
import { Index } from "@upstash/vector";

type Metadata = { genre: string, year: number };

const index = new Index<Metadata>();
```

--------------------------------

### Install Upstash Semantic Cache and Vector Packages

Source: https://upstash.com/docs/vector/sdk/semantic-cache-js

Installs the necessary packages for using the Upstash Semantic Cache and its underlying Vector database. This is a prerequisite for setting up and utilizing the caching functionality in a Node.js application.

```bash
npm install @upstash/semantic-cache @upstash/vector
```

--------------------------------

### Upsert data using cURL

Source: https://upstash.com/docs/vector/api/get-started

This snippet demonstrates how to upsert data into your Upstash Vector database using a cURL command. It requires your REST URL and token for authentication. The input is a JSON payload containing the ID and vector for the data to be inserted.

```shell
curl $UPSTASH_VECTOR_REST_URL/upsert \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"id": "id-0", "vector": [0.87, 0.99]}'
```

--------------------------------

### Start Resumable Query - cURL

Source: https://upstash.com/docs/vector/features/resumablequery

Demonstrates how to start a resumable query using a cURL command. This POST request includes the vector, topK, and metadata inclusion flag in the JSON body, authenticated via a bearer token.

```shell
curl $UPSTASH_VECTOR_REST_URL/resumable-query \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
    "vector": [0.1, 0.2],
    "topK": 2,
    "includeMetadata": true
  }'
```

--------------------------------

### POST /resumable-query

Source: https://upstash.com/docs/vector/features/resumablequery

Initiates a new resumable query. This endpoint allows you to start a query and optionally configure parameters like `maxIdle` time.

```APIDOC
## POST /resumable-query

### Description
Starts a new resumable query. This allows you to perform similarity searches and retrieve results in batches. You can specify parameters like `top_k`, `include_metadata`, and `max_idle`.

### Method
POST

### Endpoint
/resumable-query

#### Query Parameters
None

#### Request Body
- **vector** (array of floats) - Required - The query vector.
- **top_k** (integer) - Required - The number of nearest neighbors to return initially.
- **include_metadata** (boolean) - Optional - Whether to include metadata in the results. Defaults to false.
- **max_idle** (integer) - Optional - The maximum idle time in seconds before the query is automatically stopped. Defaults to 3600 seconds (1 hour).

### Request Example
```json
{
  "vector": [0.1, 0.2],
  "topK": 2,
  "includeMetadata": true,
  "maxIdle": 7200
}
```

### Response
#### Success Response (200)
- **result** (array) - The initial batch of similarity score objects.
- **handle** (object) - An object containing methods to interact with the ongoing query (e.g., `fetch_next`, `stop`).

#### Response Example
```json
{
  "result": [
    {
      "id": "vector1",
      "score": 0.95,
      "metadata": { "key": "value" }
    }
  ],
  "handle": { /* methods to continue query */ }
}
```
```

--------------------------------

### Default Upstash Vector Configuration

Source: https://upstash.com/docs/vector/sdks/php/laravel

This is the default configuration file (`config/vector.php`) for the upstash/vector-laravel package. It defines the default connection and allows specifying URL and token via environment variables.

```php
return [
    'default' => env('UPSTASH_VECTOR_CONNECTION', 'default'),

    'connections' => [
        'default' => [
            'url' => env('UPSTASH_VECTOR_REST_URL'),
            'token' => env('UPSTASH_VECTOR_REST_TOKEN'),
        ],
    ],
];
```

--------------------------------

### Handle unsuccessful REST API response

Source: https://upstash.com/docs/vector/api/get-started

This snippet illustrates the JSON response from the Upstash Vector REST API when a command execution fails. An error response includes an 'error' field with the error message and a 'status' code.

```json
{
  "error": "Unauthorized: Invalid auth token",
  "status": 401
}
```

--------------------------------

### Inject Upstash Vector Index Interface in Controller

Source: https://upstash.com/docs/vector/sdks/php/laravel

This PHP code shows how to inject the `IndexInterface` into a Laravel controller for dependency injection. This allows you to interact with the Upstash Vector index without using the facade. The example retrieves a list of namespaces.

```php
namespace App\Http\Controllers;

use Upstash\Vector\Contracts\IndexInterface;

class Controller
{
    public function index(IndexInterface $index)
    {
        $namespaces = $index->listNamespaces();
        
        return response()->json(['namespaces' => $namespaces]);
    }
}
```

--------------------------------

### GET /info - Retrieve Index Information

Source: https://upstash.com/docs/vector/overall/llms-txt

Fetches the index configuration, statistics, and namespace information for the Upstash Vector database.

```APIDOC
## GET /info

### Description
Retrieves index configuration, statistics, and namespace information.

### Method
GET

### Endpoint
/info

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl $UPSTASH_VECTOR_REST_URL/info \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

### Response
#### Success Response (200)
- **vectorCount** (integer) - The total number of vectors in the index.
- **pendingVectorCount** (integer) - The number of vectors pending processing.
- **indexSize** (integer) - The size of the index in bytes.
- **dimension** (integer) - The dimension of the vectors in the index.
- **similarityFunction** (string) - The similarity function used by the index (e.g., 'COSINE', 'DOT_PRODUCT', 'EUCLIDEAN').
- **indexType** (string) - The type of index (e.g., 'VECTOR', 'HYBRID').
- **denseIndex** (object) - Information about the dense index, if present.
  - **embeddingModel** (string) - The embedding model used for the dense index.
- **sparseIndex** (object) - Information about the sparse index, if present.
  - **embeddingModel** (string) - The embedding model used for the sparse index.
- **namespaces** (object) - An object containing statistics for each namespace.
  - **[namespaceName]** (object) - Statistics for a specific namespace.
    - **vectorCount** (integer) - The number of vectors in this namespace.

#### Response Example
```json
{
  "vectorCount": 1000,
  "pendingVectorCount": 0,
  "indexSize": 102400,
  "dimension": 1536,
  "similarityFunction": "COSINE",
  "indexType": "VECTOR",
  "denseIndex": {
    "embeddingModel": "text-embedding-ada-002"
  },
  "namespaces": {
    "default": {
      "vectorCount": 1000
    },
    "documents": {
      "vectorCount": 500
    }
  }
}
```
```

--------------------------------

### Upstash Vector API Single Query Example (cURL)

Source: https://upstash.com/docs/vector/api/endpoints/query

Demonstrates how to perform a single vector query using the Upstash Vector API with cURL. This example requires setting environment variables for the REST URL and authentication token, and sends a JSON payload with the query vector and desired top K results.

```shell
curl $UPSTASH_VECTOR_REST_URL/query \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "vector": [0.1, 0.2], "topK": 2, "includeMetadata": true }'
```

--------------------------------

### Interact with Upstash Vector using Laravel Facade

Source: https://upstash.com/docs/vector/sdks/php/laravel

This PHP code demonstrates how to use the Upstash Vector facade to interact with your index. Ensure the environment variables are set correctly. The `Vector::getInfo()` method fetches information about the index.

```php
use Upstash\Vector\Laravel\Facades\Vector;

Vector::getInfo(); // Fetches the index info.
```

--------------------------------

### Query Upstash Vector with Text (Go)

Source: https://upstash.com/docs/vector/features/hybridindexes

Provides a Go example for querying an Upstash Vector index. It initializes the index using the provided URL and token, then calls QueryData with text and top-k parameters. Error handling for the query is included. Requires the 'upstash/vector-go' package.

```Go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

	scores, err := index.QueryData(vector.QueryData{
		Data: "Upstash Vector",
		TopK: 5,
	})
}
```

--------------------------------

### Starting a Resumable Query

Source: https://upstash.com/docs/vector/features/resumablequery

Initiates a resumable query to find approximate nearest neighbors. The server returns the first batch of results and a handle to continue the query later.

```APIDOC
## POST /resumable-query

### Description
Starts a resumable query to find approximate nearest neighbors for a given vector. This allows for paginated retrieval of search results.

### Method
POST

### Endpoint
/resumable-query

### Parameters
#### Query Parameters
None

#### Request Body
- **vector** (array[float]) - Required - The query vector.
- **topK** (integer) - Optional - The maximum number of results to return per batch. Defaults to 10.
- **includeMetadata** (boolean) - Optional - Whether to include metadata in the response.
- **includeData** (boolean) - Optional - Whether to include data in the response.
- **filter** (object) - Optional - A filter expression to apply to the search.

### Request Example
```json
{
  "vector": [0.1, 0.2],
  "topK": 2,
  "includeMetadata": true
}
```

### Response
#### Success Response (200)
- **result** (array[object]) - The first batch of search results. Each object may contain 'id', 'vector', 'metadata', and 'data' fields depending on the include flags.
- **handle** (string) - A unique handle to identify the query for subsequent requests to fetch more results.

#### Response Example
```json
{
  "result": [
    {
      "id": "vec1",
      "score": 0.95,
      "metadata": {"genre": "scifi"}
    },
    {
      "id": "vec2",
      "score": 0.90,
      "metadata": {"genre": "fantasy"}
    }
  ],
  "handle": "query_handle_abc123"
}
```
```

--------------------------------

### List Namespaces - JSON Response Example

Source: https://upstash.com/docs/vector/api/endpoints/list-namespaces

Provides an example of a successful JSON response when listing namespaces. The response contains a 'result' field, which is an array of strings representing the names of the namespaces. An index always includes a default namespace represented by an empty string.

```json
{
    "result": ["", "ns0", "ns1"]
}
```

--------------------------------

### Python Range Query Example

Source: https://upstash.com/docs/vector/sdks/py/example_calls/range

Demonstrates how to execute a range query using the Upstash Vector Python SDK. It retrieves vectors with specified metadata and data inclusion, then prints the results, including the next cursor and details for each vector.

```python
from upstash_vector import Index

index = Index.from_env()

# Execute the range query
range_result = index.range(
    cursor="",
    limit=10,
    include_vectors=False,
    include_metadata=True,
    include_data=True,
)

# Print the range result
print("Next Cursor:", range_result.next_cursor)

for vector_info in range_result.vectors:
    print("ID:", vector_info.id)
    print("Vector:", vector_info.vector)
    print("Metadata:", vector_info.metadata)
    print("Data:", vector_info.data)
```

--------------------------------

### Get Index Statistics (Python)

Source: https://upstash.com/docs/vector/sdks/py/example_calls/info

Retrieves statistical information about the Upstash Vector index, including vector counts, index size, dimensions, similarity function, and namespace statistics. This method requires the `upstash-vector` library to be installed and configured with environment variables.

```python
from upstash_vector import Index

index = Index.from_env()

# Get statistical information about the index
info_result = index.info()

# Display the info result
print("Vector Count:", info_result.vector_count)
print("Pending Vector Count:", info_result.pending_vector_count)
print("Index Size:", info_result.index_size)
print("Dimension:", info_result.dimension)
print("Similarity Function:", info_result.similarity_function)

for ns, ns_info in info_result.namespaces.items():
    print("Namespace:", ns, "Vector Count:", ns_info.vector_count)
    print("Namespace:", ns, "Pending Vector Count:", ns_info.pending_vector_count)
```

--------------------------------

### Setup Upstash Semantic Cache in Node.js

Source: https://upstash.com/docs/vector/sdk/semantic-cache-js

Demonstrates how to initialize the Semantic Cache in a Node.js application. It requires creating an Upstash Vector database instance and configuring the SemanticCache with the database connection details and a minimum proximity threshold for cache hits.

```javascript
import { SemanticCache } from "@upstash/semantic-cache";
import { Index } from "@upstash/vector";

// 👇 your vector database
const index = new Index();

// 👇 your semantic cache
const semanticCache = new SemanticCache({ index, minProximity: 0.95 });

async function runDemo() {
  await semanticCache.set("Capital of Turkey", "Ankara");
  await delay(1000);

  // 👇 outputs: "Ankara"
  const result = await semanticCache.get("What is Turkey's capital?");
  console.log(result);
}

function delay(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

runDemo();
```

--------------------------------

### Query API Endpoint

Source: https://upstash.com/docs/vector/sdks/ts/commands/query

This section details the response structure for the query operation in the Upstash Vector API and provides examples of how to use the query method.

```APIDOC
## POST /query

### Description
Allows you to query the vector database to find similar vectors based on a given vector or data. You can include metadata, vectors, and data in the response based on the query parameters.

### Method
POST

### Endpoint
/query

### Parameters
#### Query Parameters
- **namespace** (string) - Optional - The namespace to query within.

#### Request Body
- **vector** (number[]) - Required if `data` is not provided - The query vector.
- **data** (string) - Required if `vector` is not provided - The data to generate a vector for querying.
- **topK** (number) - Required - The number of nearest neighbors to return.
- **includeMetadata** (boolean) - Optional - Whether to include metadata in the response.
- **includeVectors** (boolean) - Optional - Whether to include vectors in the response.
- **filter** (string) - Optional - A filter expression to apply to the query.

### Request Example
```typescript
await index.query({
  topK: 2,
  vector: [ ... ],
  includeMetadata: true,
  includeVectors: true
}, { namespace: "my-namespace" })

// Or using data:
const results = await index.query({
  data: "Movie about an adventure of a hobbit in a fantasy world.",
  includeVectors: true,
  includeMetadata: true,
  topK: 1,
  filter: "genre = 'fantasy' and title = 'Lord of the Rings'",
});

// With improved typechecking:
typedef Metadata = {
  title: string,
  genre: 'sci-fi' | 'fantasy' | 'horror' | 'action'
}

const results = await index.query<Metadata>({
  vector: [
    ... // query embedding
  ],
  includeVectors: true,
  topK: 1,
  filter: "genre = 'fantasy' and title = 'Lord of the Rings'"
})
```

### Response
#### Success Response (200)
- **Response** (QueryResult[]) - An array of query results.
  - **id** (string | number) - The ID of the resulting vector.
  - **score** (number) - The score of the vector data, calculated based on the distance metric of your index.
  - **vector** (number[]) - Optional - The resulting vector (if `includeVectors` is set to true).
  - **sparseVector** (SparseVector) - Optional - The resulting sparseVector (if `includeVectors` is set to true).
  - **metadata** (Record<string, unknown>) - Optional - The metadata of the vector (if `includeMetadata` is set to true).
  - **data** (string) - Optional - The data of the vector (if `includeData` is set to true).

#### Response Example
```json
[
  {
    "id": "6345",
    "score": 0.85,
    "vector": [],
    "metadata": {
      "sentence": "Upstash is great."
    }
  },
  {
    "id": "1233",
    "score": 0.75,
    "vector": [],
    "metadata": undefined
  }
]
```
```

--------------------------------

### Sparse Vector Operations using Python

Source: https://upstash.com/docs/vector/overall/llms-txt

Provides Python examples for upserting sparse vectors and querying them with IDF weighting using the Upstash Vector Python SDK. It covers initializing the Index, defining SparseVector objects, and applying the weighting strategy during queries.

```python
from upstash_vector import Index, Vector
from upstash_vector.types import SparseVector, WeightingStrategy

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

# Upsert sparse vectors
index.upsert(
    vectors=[
        Vector(id="sparse-1", sparse_vector=SparseVector([1, 42, 1523], [0.3, 0.8, 0.5])),
        Vector(id="sparse-2", sparse_vector=SparseVector([5, 100, 2048], [0.6, 0.4, 0.7])),
    ]
)

# Query with IDF weighting
results = index.query(
    sparse_vector=SparseVector([1, 42], [0.5, 0.9]),
    top_k=5,
    weighting_strategy=WeightingStrategy.IDF,
    include_metadata=True
)
```

--------------------------------

### Start Resumable Query - JavaScript

Source: https://upstash.com/docs/vector/features/resumablequery

Starts a resumable vector search with the Upstash Vector JavaScript SDK. This function accepts a vector, topK, and flags such as includeMetadata. It returns the initial results and functions to fetch more or stop the query.

```JavaScript
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
});

const { result, fetchNext, stop } = await index.resumableQuery({
  vector: [0.1, 0.2],
  topK: 2,
  includeMetadata: true,
});

// first batch of the results
for (let r of result) {
  console.log(r);
}
```

--------------------------------

### GET /websites/upstash-vector/info

Source: https://upstash.com/docs/vector/sdks/ts/commands/info

Retrieves the current statistics and configuration of the Upstash Vector index.

```APIDOC
## GET /websites/upstash-vector/info

### Description
Used to retrieve the stats of an index.

### Method
GET

### Endpoint
/websites/upstash-vector/info

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
// Assuming 'index' is an initialized Upstash Vector index client
const infoResponse = await index.info();
```

### Response
#### Success Response (200)
- **vectorCount** (number) - The total number of vectors in the index, that are ready to use.
- **pendingVectorCount** (number) - The number of vectors in the index, that is still processing and not ready to use.
- **indexSize** (number) - The size of the index, in bytes.
- **dimension** (number) - Dimension of the vectors.
- **similarityFunction** (string) - Name of the similarity function used in indexing and queries.
- **namespaces** (Record<string, Object>) - A map of namespaces to their information. Each namespace object contains:
  - **vectorCount** (number) - The total number of vectors in the namespace, that are ready to use.
  - **pendingVectorCount** (number) - The number of vectors in the namespace, that is still processing and not ready to use.

#### Response Example
```json
{
  "vectorCount": 17,
  "pendingVectorCount": 0,
  "indexSize": 551158,
  "dimension": 1536,
  "similarityFunction": "COSINE",
  "namespaces": {
    "": { 
      "vectorCount": 10,
      "pendingVectorCount": 0
    },
    "my-namespace": {
      "vectorCount": 7,
      "pendingVectorCount": 0
    }
  }
}
```
```

--------------------------------

### Query Vector Data with cURL

Source: https://upstash.com/docs/vector/api/endpoints/query-data

Demonstrates how to query vector data using cURL. This includes examples for single queries, queries within a namespace, and batch queries. It requires setting up environment variables for the Upstash Vector REST URL and token.

```sh
curl $UPSTASH_VECTOR_REST_URL/query-data \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "data": "What is Upstash?", "topK": 2, "includeMetadata": true }'
```

```sh
curl $UPSTASH_VECTOR_REST_URL/query-data/ns \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "data": "What is Upstash?", "topK": 2, "includeMetadata": true }'
```

```sh
curl $UPSTASH_VECTOR_REST_URL/query-data \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '[ \
        { \
          "data": "What is Upstash?", \
          "topK": 2, \
          "includeMetadata": true \
        }, \
        { \
          "data": "What is Upstash Vector?", \
          "topK": 3 \
        } \
      ]'
```

--------------------------------

### POST /resumable-query-next

Source: https://upstash.com/docs/vector/api/endpoints/resumable-query/resume

Resumes a previously started query to fetch additional results. This is useful for paginating through search results.

```APIDOC
## POST /resumable-query-next

### Description
Resumes a previously started query to fetch additional results. This is useful for paginating through search results.

### Method
POST

### Endpoint
/resumable-query-next

### Parameters
#### Request Body
- **uuid** (string) - Required - The unique identifier returned from the start resumable query request.
- **additionalK** (number) - Required - The number of additional results to fetch.

### Request Example
```sh curl theme={"system"}
curl $UPSTASH_VECTOR_REST_URL/resumable-query-next \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ \
    "uuid": "550e8400-e29b-41d4-a716-446655440000", \
    "additionalK": 2 \
  }'
```

### Response
#### Success Response (200)
- **Scores** (Object[]) - An array of search results, where each object represents a vector.
  - **id** (string) - The id of the vector.
  - **score** (number) - The similarity score of the vector, calculated based on the distance metric of your index.
  - **vector** (number[]) - The dense vector value for dense and hybrid indexes.
  - **sparseVector** (Object[]) - The sparse vector value for sparse and hybrid indexes.
    - **indices** (number[]) - Indices of the non-zero valued dimensions.
    - **values** (number[]) - Values of the non-zero valued dimensions.
  - **metadata** (Object) - The metadata of the vector, if any.
  - **data** (string) - The unstructured data of the vector, if any.

#### Response Example
```json
{
  "Scores": [
    {
      "id": "vector-1",
      "score": 0.95,
      "vector": [0.1, 0.2, 0.3],
      "sparseVector": {
        "indices": [1, 5, 10],
        "values": [0.5, 0.2, 0.1]
      },
      "metadata": {
        "genre": "fiction"
      },
      "data": "Example data for vector-1"
    }
  ]
}
```
```

--------------------------------

### Start Resumable Query with Max Idle Time

Source: https://upstash.com/docs/vector/features/resumablequery

Initiates a resumable query and allows configuration of the maximum idle time before the query is automatically stopped. This helps prevent resource leaks for queries that are no longer actively being used. The `max_idle` parameter is specified in seconds. Examples are shown for Python, JavaScript, Go, and curl.

```python
result, handle = index.resumable_query(
    vector=[0.1, 0.2],
    top_k=2,
    include_metadata=True,
    max_idle = 7200, # two hours, in seconds
)
```

```javascript
const { result, fetchNext, stop } = await index.resumableQuery({
  vector: [0.1, 0.2],
  topK: 2,
  includeMetadata: true,
  maxIdle: 7200, // two hours, in seconds
});
```

```go
scores, handle, err := index.ResumableQuery(vector.ResumableQuery{
	Vector:          []float32{0.1, 0.2},
	TopK:            2,
	IncludeMetadata: true,
	MaxIdle:         7200, // two hours, in seconds
})
```

```curl
curl $UPSTASH_VECTOR_REST_URL/resumable-query \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
    "vector": [0.1, 0.2],
    "topK": 2,
    "includeMetadata": true,
    "maxIdle": 7200
  }'
```

--------------------------------

### Access Specific Upstash Vector Connection

Source: https://upstash.com/docs/vector/sdks/php/laravel

This PHP code demonstrates how to access a specific Upstash Vector connection by name using the `connection` method on the Vector facade. This is useful when you have configured multiple connections in your `config/vector.php` file.

```php
use Upstash\Vector\Laravel\Facades\Vector;

Vector::connection('another')->getInfo();
```

--------------------------------

### Query Upstash Vector Index with Improved Typechecking (TypeScript)

Source: https://upstash.com/docs/vector/sdks/ts/commands/query

This example showcases using TypeScript generics with the `index.query` method to provide strong typing for metadata. This enhances type safety and autocompletion when accessing metadata fields.

```typescript
type Metadata = {
    title: string,
    genre: 'sci-fi' | 'fantasy' | 'horror' | 'action'
  }

  const results = await index.query<Metadata>({
    vector: [
      ... // query embedding
    ],
    includeVectors: true,
    topK: 1,
    filter: "genre = 'fantasy' and title = 'Lord of the Rings'"
  })

  if (results[0].metadata) {
    // Since we passed the Metadata type parameter above,
    // we can interact with metadata fields without having to
    // do any typecasting.
    const { title, genre } = results[0].metadata;
    console.log(`The best match in fantasy was ${title}`)
  }
```

--------------------------------

### Upstash Vector API Namespace Query Example (cURL)

Source: https://upstash.com/docs/vector/api/endpoints/query

Shows how to execute a query within a specific namespace using the Upstash Vector API via cURL. Similar to a single query, it uses environment variables for credentials and a JSON payload, but targets the '/query/ns' endpoint.

```shell
curl $UPSTASH_VECTOR_REST_URL/query/ns \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "vector": [0.1, 0.2], "topK": 2, "includeMetadata": true }'
```

--------------------------------

### Query with Distribution-Based Score Fusion (Go)

Source: https://upstash.com/docs/vector/features/hybridindexes

Provides an example of a hybrid query using DBSF in Go. It sets up the Upstash Vector index client and makes a query request including the vector, sparse vector, and the DBSF fusion algorithm.

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

	scores, err := index.Query(vector.Query{
		Vector: []float32{0.5, 0.4},
		SparseVector: &vector.SparseVector{
			Indices: []int32{3, 5},
			Values:  []float32{0.3, 05},
		},
		FusionAlgorithm: vector.FusionAlgorithmDBSF,
	})
}
```

--------------------------------

### Get Index Info using Python SDK

Source: https://upstash.com/docs/vector/overall/llms-txt

Retrieve index configuration, statistics, and namespace information using the Upstash Vector Python SDK. Initialize the Index with your REST URL and token, then call the info() method. The output includes vector counts, index size, dimension, similarity function, index type, and namespace statistics.

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

info = index.info()

print(f"Total vectors: {info.vector_count}")
print(f"Index size: {info.index_size} bytes")
print(f"Dimension: {info.dimension}")
print(f"Similarity: {info.similarity_function}")
print(f"Type: {info.index_type}")

# Namespace info
for namespace, stats in info.namespaces.items():
    print(f"Namespace '{namespace}': {stats['vectorCount']} vectors")
```

--------------------------------

### Python Range Query by ID Prefix

Source: https://upstash.com/docs/vector/sdks/py/example_calls/range

Shows how to use the 'range' method to retrieve vectors whose IDs start with a specific prefix. This is useful for targeted retrieval of related vector entries.

```python
index.range(prefix="id-")
```

--------------------------------

### Start Resumable Query - Python

Source: https://upstash.com/docs/vector/features/resumablequery

Initiates a resumable nearest neighbor search using the Upstash Vector Python SDK. It takes a vector, topK, and optional flags like include_metadata. It returns the first batch of results and a handle to continue the query.

```Python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

result, handle = index.resumable_query(
    vector=[0.1, 0.2],
    top_k=2,
    include_metadata=True,
)

# first batch of the results
for r in result:
    print(r)
```

--------------------------------

### Query Data with Upstash Vector API

Source: https://upstash.com/docs/vector/features/metadata

This section details how to query data from the Upstash Vector index. It includes examples for JavaScript, PHP, and cURL, demonstrating how to set parameters like `data`, `topK`, and `includeData`.

```APIDOC
## POST /query-data

### Description
Queries the vector index for similar data points based on the provided query data. Supports returning the vector data itself if `includeData` is set to true.

### Method
POST

### Endpoint
/query-data

### Parameters
#### Query Parameters
None

#### Request Body
- **data** (string) - Required - The query string or vector data to search for.
- **topK** (integer) - Optional - The number of nearest neighbors to return. Defaults to a predefined value if not specified.
- **includeData** (boolean) - Optional - If true, the vector data associated with the results will be included in the response. Defaults to false.

### Request Example
```json
{
  "data": "What is Upstash?",
  "includeData": true,
  "topK": 3
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the matching vector.
- **score** (float) - The similarity score of the matching vector.
- **data** (object) - The actual vector data, present only if `includeData` was true in the request.

#### Response Example
```json
[
  {
    "id": "vector_id_1",
    "score": 0.95,
    "data": {
      "content": "Upstash is a serverless data platform."
    }
  }
]
```
```

--------------------------------

### Start Resumable Query - Go

Source: https://upstash.com/docs/vector/features/resumablequery

Initiates a resumable vector search using the Upstash Vector Go SDK. It requires a vector, topK, and optional parameters like IncludeMetadata. The function returns the first set of scores and a handle for subsequent operations.

```Go
package main

import (
	"fmt"
	"log"

	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

	scores, handle, err := index.ResumableQuery(vector.ResumableQuery{
		Vector:          []float32{0.1, 0.2},
		TopK:            2,
		IncludeMetadata: true,
	})
	if err != nil {
		log.Fatal(err)
	}

	defer handle.Close()

	// first batch of the results
	for _, score := range scores {
		fmt.Printf("%+v\n", score)
	}
}
```

--------------------------------

### GET /index/info

Source: https://upstash.com/docs/vector/sdks/py/example_calls/info

Retrieves statistical information about the Upstash Vector index. This includes the total number of vectors, pending vectors, index size, vector dimensions, similarity function used, and statistics for each namespace.

```APIDOC
## GET /index/info

### Description
Retrieves statistical information about the Upstash Vector index. This includes the total number of vectors, pending vectors, index size, vector dimensions, similarity function used, and statistics for each namespace.

### Method
GET

### Endpoint
/index/info

### Parameters
#### Query Parameters
This endpoint does not accept any query parameters.

#### Request Body
This endpoint does not accept a request body.

### Request Example
```python
from upstash_vector import Index

index = Index.from_env()

# Get statistical information about the index
info_result = index.info()

# Display the info result
print("Vector Count:", info_result.vector_count)
print("Pending Vector Count:", info_result.pending_vector_count)
print("Index Size:", info_result.index_size)
print("Dimension:", info_result.dimension)
print("Similarity Function:", info_result.similarity_function)

for ns, ns_info in info_result.namespaces.items():
    print("Namespace:", ns, "Vector Count:", ns_info.vector_count)
    print("Namespace:", ns, "Pending Vector Count:", ns_info.pending_vector_count)
```

### Response
#### Success Response (200)
- **vector_count** (integer) - The total number of vectors in the index.
- **pending_vector_count** (integer) - The number of vectors that are currently pending (not yet fully processed).
- **index_size** (integer) - The size of the index in bytes.
- **dimension** (integer) - The number of dimensions the index has.
- **similarity_function** (string) - The similarity function chosen for the index (e.g., 'COSINE', 'EUCLID', 'DOTPRODUCT').
- **namespaces** (object) - A map of namespace names to their statistics.
  - **[namespace_name]** (object) - Statistics for a specific namespace.
    - **vector_count** (integer) - The number of vectors in this namespace.
    - **pending_vector_count** (integer) - The number of pending vectors in this namespace.

#### Response Example
```json
{
  "vector_count": 1500,
  "pending_vector_count": 50,
  "index_size": 1024000,
  "dimension": 128,
  "similarity_function": "COSINE",
  "namespaces": {
    "default": {
      "vector_count": 1000,
      "pending_vector_count": 20
    },
    "user_data": {
      "vector_count": 500,
      "pending_vector_count": 30
    }
  }
}
```
```

--------------------------------

### Apply IDF Weighting Strategy to Upstash Vector Queries

Source: https://upstash.com/docs/vector/features/sparseindexes

Demonstrates how to apply the Inverse Document Frequency (IDF) weighting strategy when querying an Upstash Vector index. This method is useful for algorithms like BM25, as it increases the relevance of rarer terms. The examples show the basic setup for connecting to the index and performing a query with IDF weighting enabled.

```python
from upstash_vector import Index
from upstash_vector.types import WeightingStrategy

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.query(
    data="Upstash Vector",
    top_k=5,
    weighting_strategy=WeightingStrategy.IDF,
)
```

```javascript
import { Index, WeightingStrategy } from "@upstash/vector";

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
});

await index.query({
  sparseVector: {
    indices: [2, 3],
    values: [0.13, 0.87],
  },
  weightingStrategy: WeightingStrategy.IDF,
  topK: 3,
});
```

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

	scores, err := index.QueryData(vector.QueryData{
		Data:              "Upstash Vector",
		TopK:              5,
		WeightingStrategy: vector.WeightingStrategyIDF,
	})
}
```

```php
use Upstash\Vector\Index;
use Upstash\Vector\DataQuery;
use Upstash\Vector\Enums\WeightingStrategy;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->queryData(new DataQuery(
  data: 'Upstash Vector',
  topK: 5,
  weightingStrategy: WeightingStrategy::INVERSE_DOCUMENT_FREQUENCY,
));
```

```shell
curl $UPSTASH_VECTOR_REST_URL/query-data \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"data": "Upstash Vector", "topK": 5, "weightingStrategy": "IDF"}'
```

--------------------------------

### Query Vectors Including Associated Data with Upstash Vector

Source: https://upstash.com/docs/vector/features/metadata

Demonstrates how to query vectors in Upstash Vector and retrieve the associated unstructured data. This is useful for finding vectors similar to a query text and also getting the original text content. Examples are provided for Python and JavaScript.

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

result = index.query(
    data="What is Upstash?",
    include_data=True,
)

for res in result:
    print(f"{res.id}: {res.data}")
```

```javascript
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

const result = await index.query({
  data: "What is Upstash?",
  includeData: true,
  topK: 3
})
```

--------------------------------

### GET /random

Source: https://upstash.com/docs/vector/api/endpoints/fetch-random

Fetches a random vector from the default namespace. If no namespace is specified, the default namespace will be used. The response will be null if the namespace is empty.

```APIDOC
## GET /random

### Description
Fetches a random vector from the default namespace.

### Method
GET

### Endpoint
/random

#### Path Parameters
- **namespace** (string) - Optional - The namespace to use. When no namespace is specified, the default namespace will be used.

### Request Example
```sh curl
curl $UPSTASH_VECTOR_REST_URL/random \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

### Response
#### Success Response (200)
- **id** (string) - The id of the vector.
- **vector** (number[]) - The dense vector value for dense and hybrid indexes.
- **sparseVector** (Object[]) - The sparse vector value for sparse and hybrid indexes.
  - **indices** (number[]) - Indices of the non-zero valued dimensions.
  - **values** (number[]) - Values of the non-zero valued dimensions.

#### Response Example
```json
{
    "result": {
        "id": "id-0",
        "vector": [0.1, 0.2]
    }
}
```
```

--------------------------------

### Get Index Info using JavaScript SDK

Source: https://upstash.com/docs/vector/overall/llms-txt

Retrieve index configuration, statistics, and namespace information using the Upstash Vector JavaScript SDK. This requires initializing the Index with your REST URL and token, then calling the info() method. The output includes vector counts, index size, dimension, similarity function, index type, and namespace statistics.

```javascript
import { Index } from "@upstash/vector";

const index = new Index({
  url: process.env.UPSTASH_VECTOR_REST_URL,
  token: process.env.UPSTASH_VECTOR_REST_TOKEN,
});

const info = await index.info();

console.log(`Total vectors: ${info.vectorCount}`);
console.log(`Pending vectors: ${info.pendingVectorCount}`);
console.log(`Index size: ${info.indexSize} bytes`);
console.log(`Dimension: ${info.dimension}`);
console.log(`Similarity function: ${info.similarityFunction}`);
console.log(`Index type: ${info.indexType}`);

if (info.denseIndex) {
  console.log(`Dense model: ${info.denseIndex.embeddingModel}`);
}

if (info.sparseIndex) {
  console.log(`Sparse model: ${info.sparseIndex.embeddingModel}`);
}

// Namespace statistics
Object.entries(info.namespaces).forEach(([name, stats]) => {
  console.log(`Namespace "${name}": ${stats.vectorCount} vectors`);
});
```

--------------------------------

### Upstash Vector API Query Response Example (JSON)

Source: https://upstash.com/docs/vector/api/endpoints/query

Provides a sample JSON response from the Upstash Vector API after a successful query. The 'result' field contains an array of objects, each representing a matched vector with its ID, similarity score, and optionally metadata.

```json
{
    "result": [
        {
            "id": "id-0",
            "score": 1.0,
            "metadata": {
                "link": "upstash.com"
            }
        },
        {
            "id": "id-1",
            "score": 0.99996454
        }
    ]
}
```

--------------------------------

### Delete Namespace Response Examples

Source: https://upstash.com/docs/vector/api/endpoints/delete-namespace

Illustrates the expected JSON responses for deleting a namespace. Includes a success response with a 'Success' message and an error response for a non-existent namespace.

```json
{
    "result": "Success"
}
```

```json
{
    "error": "Namespace ns for the index $NAME does not exist",
    "status": 404
}
```

--------------------------------

### Sparse Vector Operations using JavaScript

Source: https://upstash.com/docs/vector/overall/llms-txt

Shows how to upsert sparse vectors and query them using IDF weighting with the Upstash Vector JavaScript SDK. It includes examples of setting up the index, providing sparse vector data during upsert, and specifying the weighting strategy for queries. It also demonstrates upserting and querying text data using a BM25 model.

```javascript
import { Index, WeightingStrategy } from "@upstash/vector";

const index = new Index({
  url: process.env.UPSTASH_VECTOR_REST_URL,
  token: process.env.UPSTASH_VECTOR_REST_TOKEN,
});

// Upsert sparse vectors
await index.upsert([
  {
    id: "sparse-1",
    sparseVector: {
      indices: [1, 42, 1523, 5000],
      values: [0.3, 0.8, 0.5, 0.2]
    }
  }
]);

// Query with sparse vector and IDF weighting
const results = await index.query({
  sparseVector: {
    indices: [1, 42, 100],
    values: [0.5, 0.9, 0.3]
  },
  topK: 5,
  weightingStrategy: WeightingStrategy.IDF,
  includeMetadata: true
});

// Upsert and query text with BM25 model
await index.upsert([
  { id: "text-1", data: "serverless database platform" },
  { id: "text-2", data: "vector similarity search" }
]);

const textResults = await index.query({
  data: "serverless vector database",
  topK: 3,
  weightingStrategy: WeightingStrategy.IDF
});
```

--------------------------------

### Reset Namespace Response Example (JSON)

Source: https://upstash.com/docs/vector/api/endpoints/reset

The expected JSON response for a successful namespace reset operation in Upstash Vector. It includes a 'result' field indicating 'Success'.

```json
{
    "result": "Success"
}
```

--------------------------------

### Perform Resumable Query with Text Data (cURL)

Source: https://upstash.com/docs/vector/api/endpoints/resumable-query/start-with-data

This example demonstrates how to perform a resumable query using text data via cURL. It specifies the data to be queried, the number of top results to return, and whether to include metadata. The `maxIdle` parameter is also set for managing the query's idle time.

```sh
curl $UPSTASH_VECTOR_REST_URL/resumable-query-data \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
    "data": "Hello world",
    "topK": 2,
    "includeMetadata": true,
    "maxIdle": 3600
  }'
```

--------------------------------

### Range Vectors API

Source: https://upstash.com/docs/vector/api/endpoints/range

Ranges over vectors starting from a cursor until the end or a specified limit. Supports default and custom namespaces.

```APIDOC
## GET /range

### Description
Ranges over vectors starting (inclusive) from a cursor until the end of the vectors in the or given limit. By default, vectors from the default namespace will be iterated. You can use a different namespace by specifying it in the request path.

### Method
GET

### Endpoint
/range
/range/{namespace}

### Parameters
#### Query Parameters
- **cursor** (string) - Required - The offset to the last retrieved vector. Should be set to "0" in the initial range.
- **prefix** (string) - Optional - Prefix of the vector ids to range over.
- **limit** (number) - Required - The number of maximum vectors that you want in the response of range. (page size)
- **includeMetadata** (boolean) - Optional - Whether to include the metadata of the vectors in the response, if any. Defaults to false.
- **includeVectors** (boolean) - Optional - Whether to include the vector values in the response. Defaults to false.
- **includeData** (boolean) - Optional - Whether to include the data of the vectors in the response, if any. Defaults to false.

#### Path Parameters
- **namespace** (string) - Optional - The namespace to use. When no namespace is specified, the default namespace will be used.

### Request Example
```sh
curl $UPSTASH_VECTOR_REST_URL/range \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "cursor": "0", "limit": 2, "includeMetadata": true }'
```

```sh
curl $UPSTASH_VECTOR_REST_URL/range/ns \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "cursor": "0", "limit": 2, "includeMetadata": true }'
```

### Response
#### Success Response (200)
- **nextCursor** (string) - The offset for the next range. It will be equal to empty string if there are no other vectors to range.
- **vectors** (Object[]) - An array of vector objects.
  - **id** (string) - The id of the vector.
  - **vector** (number[]) - The dense vector value.
  - **sparseVector** (Object[]) - The sparse vector value.
    - **indices** (number[]) - Indices of the non-zero valued dimensions.
    - **values** (number[]) - Values of the non-zero valued dimensions.
  - **metadata** (Object) - The metadata of the vector, if any.
  - **data** (string) - The unstructured data of the vector, if any.

#### Response Example
```json
{
    "result": {
        "nextCursor": "2",
        "vectors": [
            {
                "id": "id-0",
                "metadata": {
                    "link": "upstash.com"
                }
            },
            {
                "id": "id-1"
            }
        ]
    }
}
```
```

--------------------------------

### Get Index Information using PHP

Source: https://upstash.com/docs/vector/sdks/php/commands/info

Fetches detailed information about the Upstash Vector index, including metadata, vector counts, and index configuration. This method requires the Upstash Vector REST URL and token for authentication. It returns an `IndexInfo` object.

```php
use Upstash\Vector\Index;

$index = new Index(
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
);

$info = $index->getInfo();
```

--------------------------------

### Upstash Vector API Batch Query Example (cURL)

Source: https://upstash.com/docs/vector/api/endpoints/query

Illustrates how to perform a batch query against the Upstash Vector API using cURL. This method allows sending multiple query objects in a single request, each with its own vector and parameters, by providing a JSON array to the '-d' flag.

```shell
curl "$UPSTASH_VECTOR_REST_URL/query" \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d \
    '[
          {
            "vector": [0.1, 0.2],
            "topK": 2,
            "includeMetadata": true
          },
          {
            "vector": [0.2, 0.3],
            "topK": 3
          }
        ]'
```

--------------------------------

### Filter Vectors by Less Than (SQL Example)

Source: https://upstash.com/docs/vector/features/filtering

This SQL-like syntax demonstrates filtering vectors where the 'population' is less than 20,000,000 or the 'geography.coordinates.longitude' is less than 30.0. The less than operator (<) is applicable to number metadata values.

```SQL
population < 20000000 OR geography.coordinates.longitude < 30.0
```

--------------------------------

### Query Upstash Vector Index by Text Data (TypeScript)

Source: https://upstash.com/docs/vector/sdks/ts/commands/query

This example demonstrates querying the Upstash Vector index using natural language text. It automatically generates an embedding for the provided data and allows for filtering based on metadata fields.

```typescript
const results = await index.query({
    data: "Movie about an adventure of a hobbit in a fantasy world.",
    includeVectors: true,
    includeMetadata: true,
    topK: 1,
    filter: "genre = 'fantasy' and title = 'Lord of the Rings'",
  });
  /*
  [
    {
      id: "1234",
      vector: [0.1, 0.2, 0.3, 0.4, 0.5],
      score: 0.9999999,
      metadata: {
        title: "Lord of The Rings",
        genre: "fantasy",
        category: "classic",
      },
    }
  ]
  */
```

--------------------------------

### Rename Namespace using Curl

Source: https://upstash.com/docs/vector/api/endpoints/rename-namespace

Example of renaming a namespace using the curl command. It specifies the old and new namespace names and includes authorization headers. The default namespace cannot be renamed.

```sh
curl $UPSTASH_VECTOR_REST_URL/rename-namespace \
    -X POST \
    -d '{ "namespace": "ns", "newNamespace": "newNs" }' \
    -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

--------------------------------

### Run Tests with Bun

Source: https://upstash.com/docs/vector/sdks/ts/contributing

Executes all project tests using Bun. Ensure that all necessary environment variables are configured before running this command to guarantee accurate test results.

```bash
bun run test
```

--------------------------------

### Upstash Vector API Response Examples

Source: https://upstash.com/docs/vector/api/endpoints/query-data

Illustrates successful and error responses from the Upstash Vector API. The success response includes query results with 'id', 'score', and optionally 'metadata'. The error response details an unprocessable entity error.

```json
{
    "result": [
        {
            "id": "id-0",
            "score": 1.0,
            "metadata": {
                "link": "upstash.com"
            }
        },
        {
            "id": "id-1",
            "score": 0.99996454
        }
    ]
}
```

```json
{
    "error": "Embedding data for this index is not allowed. The index must be created with an embedding model to use it.",
    "status": 422
}
```

--------------------------------

### Filter Vectors by Equality (SQL Example)

Source: https://upstash.com/docs/vector/features/filtering

This SQL-like syntax demonstrates filtering vectors where the 'country' is 'Turkey', 'population' equals 15,460,000, and 'is_capital' is false. The equals operator (=) is applicable to string, number, and boolean metadata values.

```SQL
country = 'Turkey' AND population = 15460000 AND is_capital = false
```

--------------------------------

### GET /vectors/range

Source: https://upstash.com/docs/vector/sdks/py/example_calls/range

Retrieves vectors from the index within a specified range. Supports filtering by prefix, pagination, and inclusion of vector data.

```APIDOC
## GET /vectors/range

### Description
Retrieves vectors from the index within a specified range. This method allows for paginated retrieval and filtering of vector IDs by a prefix. You can also control whether to include the vector embeddings, metadata, and associated data in the response.

### Method
GET

### Endpoint
/vectors/range

### Parameters
#### Query Parameters
- **cursor** (string) - Optional - A cursor to start the range query. Use `""` for the first request.
- **prefix** (string) - Optional - A string prefix to match vector IDs. All vectors with IDs that start with this prefix will be retrieved.
- **limit** (integer) - Optional - The maximum number of vectors to retrieve in a single query. Defaults to 10.
- **include_vectors** (boolean) - Optional - A boolean flag indicating whether to include vectors in the range results. Defaults to `false`.
- **include_metadata** (boolean) - Optional - A boolean flag indicating whether to include metadata in the range results. Defaults to `false`.
- **include_data** (boolean) - Optional - A boolean flag indicating whether to include data in the range results. Defaults to `false`.
- **namespace** (string) - Optional - Specifies the namespace to operate on. If not provided, the default namespace is used.

### Response
#### Success Response (200)
- **next_cursor** (string) - A cursor indicating the position to start the next range query. If `""`, there are no more results.
- **vectors** (array) - A list containing information for each vector.
  - **id** (string) - The ID of the vector.
  - **vector** (array) - The vector embedding (present if `include_vectors` is true).
  - **metadata** (object) - The metadata associated with the vector (present if `include_metadata` is true).
  - **data** (object) - The data associated with the vector (present if `include_data` is true).

#### Response Example
```json
{
  "next_cursor": "some-cursor-value",
  "vectors": [
    {
      "id": "vec1",
      "vector": [0.1, 0.2, 0.3],
      "metadata": {"genre": "sci-fi"},
      "data": {"title": "Example Book"}
    },
    {
      "id": "vec2",
      "metadata": {"genre": "fantasy"}
    }
  ]
}
```

### Request Example (Python SDK)
```python
from upstash_vector import Index

index = Index.from_env()

# Execute the range query with metadata and data included
range_result = index.range(
    cursor="",
    limit=10,
    include_vectors=False,
    include_metadata=True,
    include_data=True,
    namespace="my-namespace"
)

print("Next Cursor:", range_result.next_cursor)

for vector_info in range_result.vectors:
    print("ID:", vector_info.id)
    print("Vector:", vector_info.vector)
    print("Metadata:", vector_info.metadata)
    print("Data:", vector_info.data)

# Range with id prefix
index.range(prefix="id-")

# Scanning Whole Index
res = index.range(cursor="", limit=5)
while res.next_cursor != "":
    res = index.range(cursor=res.next_cursor, limit=10)
```
```

--------------------------------

### Upsert Vectors with Data and Metadata using Upstash Vector

Source: https://upstash.com/docs/vector/features/metadata

Demonstrates how to upsert vectors along with associated unstructured data and structured metadata using the Upstash Vector index. This allows for richer context to be stored with each vector, enabling more nuanced querying. The provided examples cover Python, JavaScript, PHP, and cURL.

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.upsert(
    [
        {
            "id": "id-0",
            "vector": [0.9215, 0.3897],
            "metadata": {"url": "https://imgur.com/z9AVZLb"},
            "data": "data-0",
        },
        {
            "id": "id-1",
            "vector": [0.3897, 0.9215],
            "data": "data-1",
        },
    ],
)
```

```javascript
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.upsert([
  {
    id: "id-0",
    vector: [0.9215, 0.3897],
    metadata: {"url": "https://imgur.com/z9AVZLb"},
    data: "data-0",
  },
  {
    id: "id-1",
    vector: [0.3897, 0.9215],
    data: "data-1",
  },
])
```

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorUpsert;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->upsertMany([
  new VectorUpsert(
    id: 'id-0',
    vector: [0.9215, 0.3897],
    data: 'data-0',
  ),
  new VectorUpsert(
    id: 'id-1',
    vector: [0.3897, 0.9215],
    data: 'data-1',
  ),
]);
```

```curl
curl $UPSTASH_VECTOR_REST_URL/upsert \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '[
            {
                "id": "id-0",
                "vector": [0.9215, 0.3897],
                "metadata": {"url": "https://imgur.com/z9AVZLb"},
                "data": "data-0"
            },
            {
                "id": "id-1",
                "vector": [0.3897, 0.9215],
                "data": "data-1"
            }
        ]'
```

--------------------------------

### Implement Reciprocal Rank Fusion (RRF) in JavaScript

Source: https://upstash.com/docs/vector/features/hybridindexes

This JavaScript example illustrates querying with Reciprocal Rank Fusion (RRF) using the Upstash Vector SDK. It includes setting up the index and executing a query that combines a dense vector with sparse vector data, specifying RRF as the fusion algorithm.

```javascript
import { FusionAlgorithm, Index } from "@upstash/vector";

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
});

await index.query({
  vector: [0.5, 0.4],
  sparseVector: {
    indices: [2, 3],
    values: [0.13, 0.87],
  },
  fusionAlgorithm: FusionAlgorithm.RRF,
  topK: 3,
});
```

--------------------------------

### List Namespaces - cURL Request

Source: https://upstash.com/docs/vector/api/endpoints/list-namespaces

Demonstrates how to list namespaces using cURL. This command sends a GET request to the Upstash Vector REST API endpoint. It requires the UPSTASH_VECTOR_REST_URL and an Authorization header with your UPSTASH_VECTOR_REST_TOKEN.

```sh
curl $UPSTASH_VECTOR_REST_URL/list-namespaces \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

--------------------------------

### Filter Vectors by Inequality (SQL Example)

Source: https://upstash.com/docs/vector/features/filtering

This SQL-like syntax demonstrates filtering vectors where the 'country' is not 'Germany', 'population' is not 12,500,000, and 'is_capital' is not true. The not equals operator (!=) is applicable to string, number, and boolean metadata values.

```SQL
country != 'Germany' AND population != 12500000 AND is_capital != true
```

--------------------------------

### Query Upstash Vector Index by Vector Embedding (TypeScript)

Source: https://upstash.com/docs/vector/sdks/ts/commands/query

This example shows how to query the Upstash Vector index using a pre-computed vector embedding. It specifies the number of top results (topK), includes metadata and vectors in the response, and optionally filters by namespace.

```typescript
await index.query({
    topK: 2,
    vector: [ ... ],
    includeMetadata: true,
    includeVectors: true
  }, { namespace: "my-namespace" })
  /*
  [
    {
      id: '6345',
      score: 0.85,
      vector: [],
      metadata: {
        sentence: "Upstash is great."
      }
    },
    {
      id: '1233',
      score: 0.75,
      vector: [],
      metadata: undefined
    },
  ]
  */
```

--------------------------------

### Implement Reciprocal Rank Fusion (RRF) in PHP

Source: https://upstash.com/docs/vector/features/hybridindexes

This PHP example demonstrates how to execute a query using Reciprocal Rank Fusion (RRF) with the Upstash Vector PHP SDK. It covers initializing the index and making a query that includes a dense vector, sparse vector data, and specifies RRF as the fusion algorithm.

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;
use Upstash\Vector\SparseVector;
use Upstash\Vector\Enums\FusionAlgorithm;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->query(new VectorQuery(
  vector: [0.5, 0.4],
  sparseVector: new SparseVector(
    indices: [3, 5],
    values: [0.3, 0.5],
  ),
  topK: 5,
  includeMetadata: true,
  fusionAlgorithm: FusionAlgorithm::RECIPROCAL_RANK_FUSION,
));
```

--------------------------------

### Manage Namespaces and Perform Operations using Python

Source: https://upstash.com/docs/vector/overall/llms-txt

Illustrates namespace management, data upsertion, querying within a namespace, listing namespaces, and deleting a namespace using the Upstash Vector Python SDK. It requires initializing the Index with URL and token, followed by operations on the index or specific namespaces.

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

# Upsert to specific namespace
index.upsert(
    vectors=[("doc-1", [0.1, 0.2, 0.3, 0.4])],
    namespace="customer-123"
)

# Query namespace
results = index.query(
    vector=[0.15, 0.25, 0.35, 0.45],
    top_k=5,
    namespace="customer-123"
)

# List namespaces
namespaces = index.list_namespaces()
print(namespaces)

# Delete namespace
index.delete_namespace("customer-123")
```

--------------------------------

### Filter Vectors by Greater Than (SQL Example)

Source: https://upstash.com/docs/vector/features/filtering

This SQL-like syntax demonstrates filtering vectors where the 'population' is greater than 10,000,000 or the 'geography.coordinates.latitude' is greater than 39.5. The greater than operator (>) is applicable to number metadata values.

```SQL
population > 10000000 OR geography.coordinates.latitude > 39.5
```

--------------------------------

### GET /info

Source: https://upstash.com/docs/vector/api/endpoints/info

Returns information about the index, including vector counts, index size, dimensions, similarity function, index type, and namespace details. Information may take time to update after changes.

```APIDOC
## GET /info

### Description
Returns information about the index, including vector counts, index size, dimensions, similarity function, index type, and namespace details. Information may take time to update after changes.

### Method
GET

### Endpoint
/info

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```sh
curl $UPSTASH_VECTOR_REST_URL/info \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

### Response
#### Success Response (200)
- **vectorCount** (number) - The total number of vectors in the index that are ready to use, across all namespaces.
- **pendingVectorCount** (number) - The total number of vectors in the index that are still processing and not ready to use, across all namespaces.
- **indexSize** (number) - The total size of the index in bytes.
- **dimension** (number) - The dimension of the vectors.
- **similarityFunction** (string) - The name of the similarity function used in indexing and queries.
- **indexType** (string) - The type of the index. Possible values: "DENSE", "SPARSE", "HYBRID"
- **denseIndex** (object) - Information about the dense vector index configuration.
  - **dimension** (number) - Dimension of the dense vectors.
  - **similarityFunction** (string) - Similarity function used for dense vector comparisons. Possible values: "COSINE", "EUCLIDEAN", "DOT_PRODUCT"
  - **embeddingModel** (string) - Name of the embedding model used for dense vectors.
- **sparseIndex** (object) - Information about the sparse vector index configuration.
  - **embeddingModel** (string) - Name of the embedding model used for sparse vectors.
- **namespaces** (object) - Map of namespace names to namespace objects.
  - **`""`** (object) - The default namespace.
    - **vectorCount** (number) - The number of vectors in the namespace that are ready to use.
    - **pendingVectorCount** (number) - The number of vectors in the namespace that are still processing and not ready to use.

#### Response Example
```json
{
  "result": {
    "vectorCount": 7,
    "pendingVectorCount": 0,
    "indexSize": 43501,
    "dimension": 1024,
    "similarityFunction": "COSINE",
    "indexType": "HYBRID",
    "denseIndex": {
      "dimension": 1024,
      "similarityFunction": "COSINE",
      "embeddingModel": "BGE_M3"
    },
    "sparseIndex": {
      "embeddingModel": "BM25"
    },
    "namespaces": {
      "": {
        "vectorCount": 6,
        "pendingVectorCount": 0
      },
      "ns": {
        "vectorCount": 1,
        "pendingVectorCount": 0
      }
    }
  }
}
```
```

--------------------------------

### Range Vectors (Default Namespace) - curl

Source: https://upstash.com/docs/vector/api/endpoints/range

This example demonstrates how to use the curl command to retrieve a range of vectors from the default namespace. It specifies the cursor, limit, and requests metadata inclusion. The endpoint is the default '/range'.

```curl
curl $UPSTASH_VECTOR_REST_URL/range \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "cursor": "0", "limit": 2, "includeMetadata": true }'
```

--------------------------------

### Upserting Vectors with Metadata in Upstash Vector

Source: https://upstash.com/docs/vector/features/metadata

Demonstrates how to associate metadata with vectors when performing an upsert operation. This metadata can be used for various purposes, such as tracking the source of the vector or for filtering search results. It shows examples for Python, JavaScript, Go, PHP, and curl, requiring Upstash Vector URL and token for initialization.

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.upsert(
    [("id-0", [0.9215, 0.3897]), {"url": "https://imgur.com/z9AVZLb"}],
)
```

```javascript
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.upsert({
  "id": "id-0",
  vector: [0.9215, 0.3897],
  metadata: {
    url: "https://imgur.com/z9AVZLb",
  },
})
```

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

	index.Upsert(vector.Upsert{
		Id:       "id-0",
		Vector:   []float32{0.9215, 0.3897},
		Metadata: map[string]any{"url": "https://imgur.com/z9AVZLb"},
	})
}
```

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorUpsert;

use function Upstash\Vector\createRandomVector;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->upsert(new VectorUpsert(
  id: 'id-0',
  vector: createRandomVector(384),
  metadata: [
    'url' => "https://imgur.com/z9AVZLb",
  ],
));
```

```shell
curl $UPSTASH_VECTOR_REST_URL/upsert \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
   "id":"id-0",
   "vector":[0.9215,0.3897],
   "metadata":{
      "url":"https://imgur.com/z9AVZLb"
   }
}'
```

--------------------------------

### Python: Reset All Namespaces in Upstash Vector

Source: https://upstash.com/docs/vector/sdks/py/example_calls/reset

Resets all namespaces within an Upstash Vector index. This is a comprehensive data deletion operation that affects the entire index. The 'upstash_vector' library must be installed.

```python
from upstash_vector import Index
index = Index.from_env()

index.reset(all=True)
```

--------------------------------

### Fetch Random Vector (curl)

Source: https://upstash.com/docs/vector/api/endpoints/fetch-random

This snippet shows how to fetch a random vector using curl. It requires setting the UPSTASH_VECTOR_REST_URL and UPSTASH_VECTOR_REST_TOKEN environment variables. The command sends a GET request to the /random endpoint.

```curl
curl $UPSTASH_VECTOR_REST_URL/random \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

--------------------------------

### Filter Vectors by Less Than or Equal To (SQL Example)

Source: https://upstash.com/docs/vector/features/filtering

This SQL-like syntax demonstrates filtering vectors where the 'population' is less than or equal to 20,000,000 or the 'geography.coordinates.longitude' is less than or equal to 30.0. The less than or equals operator (<=) is applicable to number metadata values.

```SQL
population <= 20000000 OR geography.coordinates.longitude <= 30.0
```

--------------------------------

### Delete Vectors by ID Prefix (TypeScript)

Source: https://upstash.com/docs/vector/sdks/ts/commands/delete

Deletes vectors from the index where their IDs start with a specified string prefix. This is useful for batch deletion of related vectors. Returns the count of deleted vectors.

```typescript
const response = await index.delete({
  prefix: "article_",
});
// { deleted: 3 }
```

--------------------------------

### Query Dense and Sparse Vectors with Custom Reranking (JavaScript)

Source: https://upstash.com/docs/vector/features/hybridindexes

Shows how to query dense and sparse vectors separately using the Upstash Vector JavaScript SDK. This pattern facilitates custom reranking logic implementation. The example requires the '@upstash/vector' package and asynchronous operations.

```javascript
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

const denseResults = await index.query({
  vector: [0.5, 0.4],
  topK: 3,
})

const sparseResults = await index.query({
  sparseVector: {
    indices: [2, 3],
    values: [0.13, 0.87],
  },
  topK: 3,
})

// Rerank dense and sparse results as you like here
```

--------------------------------

### Hybrid Search and Fusion Queries with JavaScript

Source: https://upstash.com/docs/vector/overall/llms-txt

This JavaScript code snippet showcases how to upsert hybrid vectors (dense and sparse) and perform queries using different fusion algorithms (RRF, DBSF) with the @upstash/vector SDK. It also includes examples of querying only dense or sparse components for custom reranking.

```javascript
import { Index, FusionAlgorithm } from "@upstash/vector";

const index = new Index({
  url: process.env.UPSTASH_VECTOR_REST_URL,
  token: process.env.UPSTASH_VECTOR_REST_TOKEN,
});

// Upsert hybrid vectors (both dense and sparse required)
await index.upsert([
  {
    id: "hybrid-1",
    vector: [0.1, 0.2, 0.3, 0.4],
    sparseVector: {
      indices: [10, 25, 150],
      values: [0.8, 0.6, 0.4]
    },
    metadata: { title: "Hybrid Document" }
  }
]);

// Query with RRF (Reciprocal Rank Fusion) - default
const rrfResults = await index.query({
  vector: [0.15, 0.25, 0.35, 0.45],
  sparseVector: { indices: [10, 25], values: [0.9, 0.7] },
  topK: 5,
  fusionAlgorithm: FusionAlgorithm.RRF,
  includeMetadata: true
});

// Query with DBSF (Distribution-Based Score Fusion)
const dbsfResults = await index.query({
  vector: [0.15, 0.25, 0.35, 0.45],
  sparseVector: { indices: [10, 25], values: [0.9, 0.7] },
  fusionAlgorithm: FusionAlgorithm.DBSF
});

// Query only dense component for custom reranking
const denseResults = await index.query({ vector: [0.15, 0.25, 0.35, 0.45] });
const sparseResults = await index.query({
  sparseVector: { indices: [10, 25], values: [0.9, 0.7] }
});
// Custom rerank logic here
```

--------------------------------

### Resume Resumable Query (cURL)

Source: https://upstash.com/docs/vector/api/endpoints/resumable-query/resume

Resumes a previously started query to fetch a specified number of additional results. This command requires the unique identifier (uuid) from the initial query and the count of additional results (additionalK) to retrieve. It sends a POST request to the resumable-query-next endpoint.

```sh
curl $UPSTASH_VECTOR_REST_URL/resumable-query-next \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "additionalK": 2
  }'
```

--------------------------------

### Get Namespace Information using PHP

Source: https://upstash.com/docs/vector/sdks/php/commands/info

Retrieves information about a specific namespace within the Upstash Vector index. This method can be called on the index object directly or on a specific namespace object obtained from `IndexInfo`. It requires the index URL and token and returns a `NamespaceInfo` object.

```php
use Upstash\Vector\Index;

$index = new Index(
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
);

// Fetch the information of the default namespace.
$defaultNamespaceInfo = $index->getNamespaceInfo();

// Fetch the information on a specific namespace.
$myNamespaceInfo = $index->namespace('my-namespace')->getNamespaceInfo();
```

--------------------------------

### Querying Vectors with Metadata in Upstash Vector

Source: https://upstash.com/docs/vector/features/metadata

Illustrates how to retrieve vectors along with their associated metadata during a query operation. This is useful for displaying contextual information or for filtering based on metadata. Examples are provided for Python, JavaScript, Go, PHP, and curl, utilizing the Upstash Vector client.

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.query(
    [0.9215, 0.3897],
    top_k=5,
    include_metadata=True,
)
```

```javascript
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.query({
  vector: [0.9215, 0.3897],
  topK: 5,
  includeMetadata: true,
})
```

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

	index.Query(vector.Query{
		Vector:          []float32{0.9215, 0.3897},
		TopK:            5,
		IncludeMetadata: true,
	})
}
```

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->query(new VectorQuery(
  vector: [0.9215, 0.3897],
  topK: 5,
  includeMetadata: true,
));
```

```shell
curl $UPSTASH_VECTOR_REST_URL/query \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
   "vector":[0.9215,0.3897],
   "topK" : 5,
   "includeMetadata": true
}'
```

--------------------------------

### Python: Reset Default Namespace in Upstash Vector

Source: https://upstash.com/docs/vector/sdks/py/example_calls/reset

Resets the default namespace of an Upstash Vector index. This action clears all vectors and metadata associated with the default namespace. Ensure the 'upstash_vector' library is installed.

```python
from upstash_vector import Index
index = Index.from_env()

index.reset()
```

--------------------------------

### Fetch Vectors by ID Prefix in PHP

Source: https://upstash.com/docs/vector/sdks/php/commands/fetch

Retrieve all vectors whose IDs start with a specified prefix from Upstash Vector. This function is useful for batch retrieval based on a naming convention. Options to include metadata, vectors, and data are available. Requires the Upstash Vector SDK for PHP and valid index credentials.

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorFetchByPrefix;

$index = new Index(
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
);

$results = $index->fetch(new VectorFetchByPrefix(
  prefix: 'users:',
  includeMetadata: true, // (optional) if true the fetch results will contain metadata.
  includeVectors: true, // (optional) if true the fetch results will contain the indexed vectors.
  includeData: true, // (optional) if true the fetch results will contain the string data.
));
```

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorFetchByPrefix;

$index = new Index(
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
);

$results = $index->namespace('my-namespace')->fetch(new VectorFetchByPrefix(
  prefix: 'users:',
  includeMetadata: true, // (optional) if true the fetch results will contain metadata.
  includeVectors: true, // (optional) if true the fetch results will contain the indexed vectors.
  includeData: true, // (optional) if true the fetch results will contain the string data.
));
```

--------------------------------

### Format Code with Bun

Source: https://upstash.com/docs/vector/sdks/ts/contributing

Formats the project's code according to the defined style guidelines using Bun. This command ensures code consistency across the project.

```bash
bun run fmt
```

--------------------------------

### Range Vectors (Specific Namespace) - curl

Source: https://upstash.com/docs/vector/api/endpoints/range

This example shows how to fetch a range of vectors from a specific namespace using curl. The request path is modified to '/range/ns' to indicate a namespace is being used. It includes cursor, limit, and metadata inclusion parameters.

```curl
curl $UPSTASH_VECTOR_REST_URL/range/ns \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "cursor": "0", "limit": 2, "includeMetadata": true }'
```

--------------------------------

### Upsert and Query in a Namespace (Python, JavaScript, Go, PHP, curl)

Source: https://upstash.com/docs/vector/features/namespaces

Demonstrates how to perform upsert and query operations within a specific namespace. This involves initializing the index, specifying the namespace, and then executing the respective operations. Namespaces are created implicitly if they don't exist.

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.upsert(
    [("id-0", [0.9215, 0.3897])],
    namespace="ns",
)

index.query(
    [0.9215, 0.3897],
    top_k=5,
    namespace="ns",
)
```

```javascript
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

const namespace = index.namespace("ns")

await namespace.upsert({
  id: "id-0",
  vector: [0.9215, 0.3897],
})

await namespace.query({
  vector: [0.9215, 0.3897],
  topK: 5,
})
```

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

	namespace := index.Namespace("ns")

	namespace.Upsert(vector.Upsert{
		Id:     "id-0",
		Vector: []float32{0.9215, 0.3897},
	})

	namespace.Query(vector.Query{
		Vector: []float32{0.9215, 0.3897},
		TopK:   5,
	})
}
```

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorUpsert;
use Upstash\Vector\VectorQuery;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$namespace = $index->namespace('ns');

$namespace->upsert(new VectorUpsert(
  id: 'id-0',
  vector: [0.9215, 0.3897],
));

$namespace->query(new VectorQuery(
  vector: [0.9215, 0.3897],
  topK: 5,
));
```

```curl
curl $UPSTASH_VECTOR_REST_URL/upsert/ns \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"id":"id-0", "vector":[0.9215,0.3897]}'

curl $UPSTASH_VECTOR_REST_URL/query/ns \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"vector":[0.9215,0.3897], "topK" : 5}'
```

--------------------------------

### Query Dense and Sparse Vectors with Custom Reranking (PHP)

Source: https://upstash.com/docs/vector/features/hybridindexes

Provides a PHP example for querying dense and sparse vectors separately with Upstash Vector. This method is suitable for implementing custom reranking strategies. The code utilizes the Upstash Vector PHP SDK and requires specific namespaces.

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;
use Upstash\Vector\SparseVector;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$denseResults = $index->query(new VectorQuery(
  vector: [0.5, 0.4],
  topK: 3,
));

$sparseResults = $index->query(new VectorQuery(
  sparseVector: new SparseVector(
    indices: [3, 5],
    values: [0.3, 0.5],
  ),
  topK: 3,
));

// Rerank dense and sparse results as you like here
```

--------------------------------

### Upsert Text Data with Upstash Vector (curl)

Source: https://upstash.com/docs/vector/features/sparseindexes

A command-line example using curl to upsert text data into an Upstash Vector index. This demonstrates direct API interaction, sending JSON data with 'id' and 'data' fields. Requires the Upstash Vector REST URL and token as environment variables.

```shell
curl $UPSTASH_VECTOR_REST_URL/upsert-data \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '[
    {"id": "id-0", "data": "Upstash Vector provides sparse embedding models."}, 
    {"id": "id-1", "data": "You can upsert text data with these embedding models."} 
  ]'
```

--------------------------------

### Query Dense and Sparse Data with Custom Reranker (curl)

Source: https://upstash.com/docs/vector/features/hybridindexes

This example uses curl to query dense and sparse data from a hybrid index with Upstash Vector. It sends separate requests for dense and sparse queries, enabling subsequent custom reranking of the results.

```shell
curl $UPSTASH_VECTOR_REST_URL/query-data \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"data": "Upstash Vector", "queryMode": "DENSE"}'

curl $UPSTASH_VECTOR_REST_URL/query-data \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"data": "Upstash Vector", "queryMode": "SPARSE"}'
```

--------------------------------

### Manage Namespaces and Perform Operations using JavaScript

Source: https://upstash.com/docs/vector/overall/llms-txt

Demonstrates how to manage namespaces, upsert data, query within a namespace, list all namespaces, and delete a namespace using the Upstash Vector JavaScript SDK. It requires initialization with URL and token, and subsequent operations are performed on index or namespace instances.

```javascript
import { Index } from "@upstash/vector";

const index = new Index({
  url: process.env.UPSTASH_VECTOR_REST_URL,
  token: process.env.UPSTASH_VECTOR_REST_TOKEN,
});

// Create namespace instance
const customerNamespace = index.namespace("customer-123");

// Upsert to namespace
await customerNamespace.upsert([
  { id: "doc-1", vector: [0.1, 0.2, 0.3, 0.4], metadata: { type: "invoice" } },
  { id: "doc-2", vector: [0.2, 0.3, 0.4, 0.5], metadata: { type: "receipt" } }
]);

// Query within namespace
const results = await customerNamespace.query({
  vector: [0.15, 0.25, 0.35, 0.45],
  topK: 5,
  includeMetadata: true
});

// List all namespaces
const namespaces = await index.listNamespaces();
console.log(namespaces); // ["", "customer-123", "customer-456"]

// Delete namespace
await index.deleteNamespace("customer-123");
```

--------------------------------

### Delete Namespace using cURL

Source: https://upstash.com/docs/vector/api/endpoints/delete-namespace

Example of deleting a namespace using the cURL command-line tool. This command sends a DELETE request to the specified Upstash Vector REST API endpoint, including authorization headers.

```sh
curl $UPSTASH_VECTOR_REST_URL/delete-namespace/ns \
  -X DELETE \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

--------------------------------

### Python: Sparse/Hybrid Resumable Query with Advanced Options

Source: https://upstash.com/docs/vector/sdks/py/example_calls/resumable-query

Illustrates how to perform a resumable query for sparse or hybrid indexes, including advanced options like sparse vectors, weighting strategies, and fusion algorithms. It shows fetching initial results and subsequent batches.

```python
from upstash_vector.types import SparseVector, WeightingStrategy, FusionAlgorithm

scores, handle = index.resumable_query(
    vector=[0.1, 0.1],
    sparse_vector=([0], [0.1]),
    top_k=2,
    include_vectors=True,
    include_metadata=True,
    include_data=True,
    weighting_strategy=WeightingStrategy.IDF,
    fusion_algorithm=FusionAlgorithm.DBSF,
    namespace="hybrid-ns",
)

with handle:
    for s in scores:
        print(s.id, getattr(s, "vector", None), getattr(s, "sparse_vector", None))
    more = handle.fetch_next(1)
    print("more:", more)
```

--------------------------------

### Upsert Data in Upstash Vector (curl)

Source: https://upstash.com/docs/vector/api/endpoints/upsert-data

This snippet demonstrates how to upsert single or multiple data entries into Upstash Vector using curl. It includes examples for both default and specified namespaces. Ensure your index is created with an embedding model.

```curl
curl $UPSTASH_VECTOR_REST_URL/upsert-data \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '[ 
      { "id": "id-0", "data": "Upstash is a serverless data platform.", "metadata": { "link": "upstash.com" } }, 
      { "id": "id-1", "data": "Upstash Vector is a serverless vector database." } 
    ]'
```

```curl
curl $UPSTASH_VECTOR_REST_URL/upsert-data/ns \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "id": "id-2", "data": "Upstash is a serverless data platform.", "metadata": { "link": "upstash.com" } }'
```

--------------------------------

### GET /websites/upstash-vector/fetch

Source: https://upstash.com/docs/vector/sdks/ts/commands/fetch

Retrieves vectors by their IDs. You can fetch single or multiple vectors. The request can be made using an array of IDs or a payload object containing IDs and optional prefix. Metadata, vectors, and data can be optionally included in the response.

```APIDOC
## GET /websites/upstash-vector/fetch

### Description
Retrieves vectors from the Upstash Vector database by their unique identifiers or a specified prefix.

### Method
GET

### Endpoint
`/websites/upstash-vector/fetch`

### Parameters
#### Query Parameters
- **IDs** (string[] | number[]) - Required - The IDs of the vectors to fetch. This can be provided directly as a query parameter.
- **FetchPayload** (object) - Required - An object containing fetch parameters:
  - **ids** (string[] | number[]) - The IDs of the vectors you want to fetch.
  - **prefix** (string) - Optional - An ID prefix to match vector IDs. Use with caution for large datasets; consider the `range` command for pagination.

#### Query Parameters for Options
- **Options** (object) - Optional - An object containing fetch options:
  - **includeMetadata** (boolean) - Optional - If true, includes the metadata of the vectors in the response. Defaults to false.
  - **includeVectors** (boolean) - Optional - If true, includes the vector data itself in the response. Defaults to false.
  - **includeData** (boolean) - Optional - If true, includes the associated data field for each vector. Defaults to false.
  - **namespace** (string) - Optional - The namespace from which to fetch vectors. If not provided, the default namespace is used.

### Request Example
```typescript
// Fetching vectors by IDs
await index.fetch(["2", "3"]);
// Response: [{ id: "2" }, { id: "3" }]

// Fetching vectors with a prefix
await index.fetch({ prefix: "test-" });
// Response: [{ id: "test-1" }, { id: "test-2" }, { id: "test-3" }]

// Fetching vectors with options
await index.fetch(["1"], { includeMetadata: true, includeVectors: true });
```

### Response
#### Success Response (200)
- **FetchResult[]** (Vector[]) - An array of fetch results. Each element is either a Vector object or null if the vector was not found.
  - **id** (string | number) - The ID of the vector.
  - **vector** (number[]) - Optional - The vector data, included if `includeVectors` is true.
  - **sparseVector** (SparseVector) - Optional - The sparse vector data, included if `includeVectors` is true.
  - **metadata** (Record<string, unknown>) - Optional - The metadata associated with the vector, included if `includeMetadata` is true.
  - **data** (string) - Optional - The data field of the vector, included if `includeData` is true.

#### Response Example
```json
[
  {
    "id": "2",
    "vector": [0.1, 0.2, 0.3],
    "metadata": {"genre": "sci-fi"}
  },
  {
    "id": "3",
    "vector": [0.4, 0.5, 0.6]
  }
]
```

#### Not Found Response Example
```json
[
  {
    "id": "2"
  },
  null
]
```
```

--------------------------------

### Delete Vectors by ID Prefix (Python)

Source: https://upstash.com/docs/vector/sdks/py/example_calls/delete

Deletes all vectors whose IDs start with a specified prefix. This is useful for removing groups of vectors identified by a common naming convention. The function returns the count of vectors that were removed.

```python
index.delete(prefix="id-")
```

--------------------------------

### Query Upstash Vector Index (Python, JavaScript, Go, PHP, cURL)

Source: https://upstash.com/docs/vector/overall/getstarted

This snippet shows how to perform a similarity search on an Upstash Vector index. It requires the index URL and token. The input is a query vector and parameters like `top_k` for the number of results and `include_metadata`. The output is a list of the most similar vectors.

```python
from upstash_vector import Index

index = Index(url="UPSTASH_VECTOR_REST_URL", token="UPSTASH_VECTOR_REST_TOKEN")

index.query(
    vector=[0.6, 0.8],
    top_k=3,
    include_metadata=True,
)
```

```javascript
import { Index } from "@upstash/vector";

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.query({ vector: [0.6, 0.8], topK: 3, includeMetadata: true })
```

```go
import "github.com/upstash/vector-go"

func main() {
  index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

  index.Query(vector.Query{
	  Vector:          []float32{0.6, 0.8},
	  TopK:            3,
	  IncludeMetadata: true,
  })
}
```

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;

$index = new Index(
  url: '<UPSTASH_VECTOR_REST_URL>',
  token: '<UPSTASH_VECTOR_REST_TOKEN>',
);

$index->query(new VectorQuery(
  vector: [0.6, 0.8],
  topK: 3,
  includeMetadata: true,
));
```

```shell
curl $UPSTASH_VECTOR_REST_URL/query \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"vector": [0.6, 0.8], "topK": 3, "includeMetadata": "true"}'
```

--------------------------------

### Query Dense and Sparse Data with Custom Reranker (JavaScript)

Source: https://upstash.com/docs/vector/features/hybridindexes

This JavaScript example shows how to query dense and sparse data from a hybrid index using the Upstash Vector client. It separates queries for dense and sparse vectors, enabling custom reranking logic for the retrieved results.

```javascript
import { Index, QueryMode } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

const denseResults = await index.query({
  data: "Upstash Vector",
  queryMode: QueryMode.DENSE,
})

const sparseResults = await index.query({
  data: "Upstash Vector",
  queryMode: QueryMode.SPARSE,
})

// Rerank dense and sparse results as you like here
```

--------------------------------

### Get Index Info using cURL

Source: https://upstash.com/docs/vector/api/endpoints/info

This snippet shows how to retrieve index information using a cURL command. It requires the Upstash Vector REST URL and a bearer token for authorization. The response contains various metrics about the index.

```bash
curl $UPSTASH_VECTOR_REST_URL/info \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

--------------------------------

### Query Vectors with Metadata and Data (Python)

Source: https://upstash.com/docs/vector/sdks/py/example_calls/query

Demonstrates how to retrieve vectors from an index using the `query` method. It includes options to include metadata, data, and specifies the number of top results (`top_k`) and filtering criteria. This method is suitable for single similarity search operations.

```python
import random

from upstash_vector import Index

index = Index.from_env()

# Generate a random vector for similarity comparison
dimension = 128  # Adjust based on your index's dimension
query_vector = [random.random() for _ in range(dimension)]

# Execute the query
query_result = index.query(
    vector=query_vector,
    include_metadata=True,
    include_data=True,
    include_vectors=False,
    top_k=5,
    filter="genre = 'fantasy' and title = 'Lord of the Rings'",
)

# Print the query result
for result in query_result:
    print("Score:", result.score)
    print("ID:", result.id)
    print("Vector:", result.vector)
    print("Metadata:", result.metadata)
    print("Data:", result.data)
```

--------------------------------

### Upsert Raw Text Data with Upstash Vector

Source: https://upstash.com/docs/vector/features/metadata

Shows how to upsert raw text directly as data associated with a vector in Upstash Vector. This is useful for storing unstructured text that can be retrieved later. Examples are provided for Python, JavaScript, PHP, and cURL.

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.upsert(
    [
        {
            "id": "id-2",
            "data": "Upstash is a serverless data platform.",
        },
    ],
)
```

```javascript
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.upsert([
  {
    id: "id-2",
    data: "Upstash is a serverless data platform.",
  }
])
```

```php
use Upstash\Vector\Index;
use Upstash\Vector\DataUpsert;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->upsertData(new DataUpsert(
  id: 'id-0',
  data: 'Upstash is a serverless data platform.',
));
```

```curl
curl $UPSTASH_VECTOR_REST_URL/upsert-data \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
            "id": "id-0",
            "data": "Upstash is a serverless data platform."
          }'
```

--------------------------------

### Retrieve Vector Ranges with Metadata (Python, JavaScript, Go, PHP, cURL)

Source: https://upstash.com/docs/vector/features/metadata

Shows how to retrieve a range of vectors from the database, optionally including metadata. This requires the vector endpoint URL, token, and parameters for the cursor and limit. Metadata inclusion is a boolean flag. The PHP example omits the cursor as it is not a required parameter for that SDK.

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.range(
    cursor="0",
    limit=3,
    include_metadata=True,
)
```

```javascript
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.range({
  cursor: "0",
  limit: 3,
  includeMetadata: true,
})
```

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

	index.Range(vector.Range{
		Cursor:          "0",
		Limit:           3,
		IncludeMetadata: true,
	})
}
```

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorRange;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->range(new VectorRange(
  limit: 3,
  includeMetadata: true,
));
```

```shell
curl $UPSTASH_VECTOR_REST_URL/range \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "cursor" : "0",  "limit" : 3, "includeMetadata": true}'
```

--------------------------------

### Query Vectors with Metadata Filter (Python, JavaScript, Go, PHP, curl)

Source: https://upstash.com/docs/vector/features/filtering

Perform a vector similarity search with a metadata filter. This example demonstrates querying for vectors where the 'population' is greater than or equal to 1,000,000 and the 'geography.continent' is 'Asia'. The 'topK' parameter specifies the number of results, and 'includeMetadata' ensures metadata is returned. This functionality is available across multiple languages and via curl.

```Python
from upstash_vector import Index

index = Index(
  url="UPSTASH_VECTOR_REST_URL",
  token="UPSTASH_VECTOR_REST_TOKEN",
)

index.query(
  vector=[0.9215, 0.3897],
  filter="population >= 1000000 AND geography.continent = 'Asia'",
  top_k=5,
  include_metadata=True
)
```

```JavaScript
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.query({
  vector: [0.9215, 0.3897],
  filter: "population >= 1000000 AND geography.continent = 'Asia'",
  topK: 5,
  includeMetadata: true,
});
```

```Go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

	index.Query(vector.Query{
		Vector:          []float32{0.9215, 0.3897},
		Filter:          `population >= 1000000 AND geography.continent = 'Asia'`, 
		TopK:            5,
		IncludeMetadata: true,
	})
}
```

```PHP
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->query(new VectorQuery(
  vector: [0.9215, 0.3897],
  topK: 5,
  includeMetadata: true,
  filter: "population >= 1000000 AND geography.continent = 'Asia'",
));
```

```curl
curl $UPSTASH_VECTOR_REST_URL/query \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
   "vector":[0.9215,0.3897],
   "topK" : 5,
   "filter": "population >= 1000000 AND geography.continent = \"Asia\"",
   "includeMetadata": true
}'
```

--------------------------------

### Query Data with Upstash Vector PHP SDK

Source: https://upstash.com/docs/vector/sdks/php/commands/query

Query the Upstash Vector index using a string, which is automatically converted to embeddings. This example requires an index configured with an embedding model. It takes a string as input and returns topK results, optionally including data.

```php
use Upstash\Vector\Index;
use Upstash\Vector\DataQuery;

$index = new Index(
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
);

$results = $index->queryData(new DataQuery(
  data: 'What is the capital of France?',
  topK: 1, // to only return 1 result.
  includeData: true,
));
```

```php
use Upstash\Vector\Index;
use Upstash\Vector\DataQuery;

$index = new Index(
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
);

$results = $index->namespace('my-namespace')->queryData(new DataQuery(
  data: 'What is the capital of France?',
  topK: 1, // to only return 1 result.
  includeData: true,
));
```

--------------------------------

### Multilingual Queries with Upstash Semantic Cache (TypeScript)

Source: https://upstash.com/docs/vector/sdk/semantic-cache-js

Demonstrates performing multilingual queries with the Upstash Semantic Cache. It requires an embedding model that supports multiple languages. The example shows setting a value in English and retrieving it using a German query.

```typescript
await semanticCache.set("German Chancellor", "Olaf Scholz");
await delay(1000);

// 👇 "Who is the chancellor of Germany?" -> outputs "Olaf Scholz"
const result = await semanticCache.get("Wer ist der Bundeskanzler von Deutschland?");
```

--------------------------------

### Upsert Text Data with Upstash Vector (Go)

Source: https://upstash.com/docs/vector/features/sparseindexes

Demonstrates how to upsert text data into an Upstash Vector index using Go. The function 'UpsertDataMany' handles the embedding of text data. Ensure the 'vector-go' SDK is installed and provide valid REST URL and token.

```Go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

	err := index.UpsertDataMany([]vector.UpsertData{
		{
			Id:   "id-0",
			Data: "Upstash Vector provides sparse embedding models.",
		},
		{
			Id:   "id-1",
			Data: "You can upsert text data with these embedding models.",
		},
	})
}
```

--------------------------------

### Upsert Text Data with Upstash Vector (JavaScript)

Source: https://upstash.com/docs/vector/features/sparseindexes

Upserts text data into an Upstash Vector index using JavaScript. The index automatically embeds the provided text. This example requires the '@upstash/vector' package and correct Upstash Vector credentials.

```JavaScript
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.upsert([
  {
    id: 'id-0',
    data: "Upstash Vector provides dense and sparse embedding models.",
  }
])
```

--------------------------------

### Query with IDF Weighting Strategy

Source: https://upstash.com/docs/vector/features/sparseindexes

This section explains how to use the Inverse Document Frequency (IDF) weighting strategy in Upstash Vector queries. IDF is useful for algorithms like BM25 to give more importance to rarer terms in the collection. The documentation provides examples in Python, JavaScript, Go, PHP, and curl.

```APIDOC
## POST /query-data

### Description
Allows querying the vector index with a specified weighting strategy, such as Inverse Document Frequency (IDF). This strategy helps in prioritizing rarer terms for better search relevance, particularly with algorithms like BM25.

### Method
POST

### Endpoint
/query-data

### Parameters
#### Query Parameters
- **data** (string) - Required - The query text or sparse vector data.
- **topK** (integer) - Required - The number of nearest neighbors to return.
- **weightingStrategy** (string) - Required - The strategy to use for weighting query values. Use `"IDF"` for Inverse Document Frequency.

### Request Example
```json
{
  "data": "Upstash Vector",
  "topK": 5,
  "weightingStrategy": "IDF"
}
```

### Response
#### Success Response (200)
- **results** (array) - An array of matching vectors, each with an ID, score, and optional vector data.

#### Response Example
```json
{
  "results": [
    {
      "id": "doc1",
      "score": 0.95,
      "vector": [0.1, 0.2, 0.3]
    }
  ]
}
```

#### Error Handling
- **400 Bad Request**: If the request parameters are invalid.
- **401 Unauthorized**: If the API key is invalid.
- **404 Not Found**: If the index or endpoint does not exist.
- **500 Internal Server Error**: If there is a server-side issue.
```

--------------------------------

### Range Method with Basic Options (TypeScript)

Source: https://upstash.com/docs/vector/sdks/ts/commands/range

Demonstrates the basic usage of the range method to fetch vectors with pagination, including metadata. The response includes a cursor for the next page and the vector details.

```typescript
const responseRange = await index.range(
    {
      cursor: 0,
      limit: 2,
      includeMetadata: true,
    },
    { namespace: "my-namespace" }
  );

  /*
  {
    nextCursor: '2',
    vectors: [
      {
        id: '0',
        metadata: {
          keyword: "Vector"
        }
      },
      {
        id: '19',
        metadata: {
          keyword: "Redis"
        }
      }
    ]
  }
  */
```

--------------------------------

### Stop Resumable Query Response Example

Source: https://upstash.com/docs/vector/api/endpoints/resumable-query/stop

This snippet shows the expected JSON response when a resumable query is successfully stopped using the Upstash Vector API. The response contains a 'result' field indicating the success status.

```json
{
  "result": "Success"
}
```

--------------------------------

### Filtering Query Results by Metadata in Upstash Vector

Source: https://upstash.com/docs/vector/features/metadata

Demonstrates how to apply a metadata filter to narrow down query results. This allows for more targeted searches based on specific metadata attributes. The example shows the 'filter' parameter in Python, with a placeholder for JavaScript, indicating the capability to filter results based on metadata content.

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.query(
    [0.9215, 0.3897],
    top_k=5,
    include_metadata=True,
    filter="url GLOB '*imgur.com*'",
)
```

```javascript
import { Index } from "@upstash/vector"

```

--------------------------------

### Index Info API

Source: https://upstash.com/docs/vector/sdks/php/commands/info

Fetch detailed information about your Upstash Vector index. This includes metadata, ready and pending vectors, similarity function, and associated namespaces.

```APIDOC
## GET /v1/indexes/{index_name}/info

### Description
Retrieves comprehensive information about the specified Upstash Vector index, including vector counts, index size, and configuration details.

### Method
GET

### Endpoint
`/v1/indexes/{index_name}/info`

### Parameters
#### Path Parameters
- **index_name** (string) - Required - The name of the index.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **vectorCount** (integer) - The number of vectors ready to query.
- **pendingVectorCount** (integer) - The number of vectors currently being indexed.
- **indexSize** (integer) - The size of the index in bytes.
- **dimension** (integer) - The dimensionality of the vectors in the index.
- **similarityFunction** (string) - The similarity function used by the index (e.g., 'COSINE', 'EUCLID', 'DOTPRODUCT').

#### Response Example
```json
{
  "vectorCount": 1000,
  "pendingVectorCount": 50,
  "indexSize": 1024000,
  "dimension": 1536,
  "similarityFunction": "COSINE"
}
```
```

--------------------------------

### Python: Fetch Vectors by IDs with Full Data

Source: https://upstash.com/docs/vector/sdks/py/example_calls/fetch

This Python snippet demonstrates how to fetch multiple vectors from an Upstash Vector index using their IDs. It includes options to retrieve the vector data, metadata, and associated data for each fetched vector. The `Index.from_env()` method is used for index initialization, assuming environment variables are configured.

```python
from upstash_vector import Index

index = Index.from_env()

# Specify the identifiers of vectors to be fetchedids_to_fetch = ["id-1", "id-2", "id-3"]

# Fetch the specified vectors with vectors and metadata included
fetch_result = index.fetch(
    ids=ids_to_fetch,
    include_vectors=True,
    include_metadata=True,
    include_data=True,
)

# Display the fetched vectors
for vector_info in fetch_result:
    print("ID:", vector_info.id)
    print("Vector:", vector_info.vector)
    print("Metadata:", vector_info.metadata)
    print("Data:", vector_info.data)
```

--------------------------------

### Delete Vectors by ID Prefix using PHP

Source: https://upstash.com/docs/vector/sdks/php/commands/delete-vectors

Deletes all vectors whose IDs start with a specified prefix. This is useful for logically grouped vectors. Requires the Upstash Vector SDK and specific classes for prefix deletion. Input is a prefix string.

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorDeleteByPrefix;

$index = new Index(
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
);

$index->delete(new VectorDeleteByPrefix(
  prefix: 'users:',
));
```

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorDeleteByPrefix;

$index = new Index(
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
);

$index->namespace('my-namespace')->delete(new VectorDeleteByPrefix(
  prefix: 'users:',
));
```

--------------------------------

### Sparse Vector Representation Example in Python

Source: https://upstash.com/docs/vector/features/sparseindexes

This code snippet demonstrates the structure of sparse vectors in Python. Sparse vectors are represented by two arrays: one for the indices of non-zero dimensions and another for their corresponding values. This contrasts with dense vectors which have values for all dimensions.

```python
dense = [0.1, 0.3, , ...thousands of non-zero values..., 0.5, 0.2]

sparse = (
    [23, 42, 5523, 123987, 240001], # some low number of dimension indices
    [0.1, 0.3, 0.1, 0.2, 0.5], # non-zero values corresponding to dimensions
)
```

--------------------------------

### Filter Vectors by Metadata with Upstash Vector PHP SDK

Source: https://upstash.com/docs/vector/sdks/php/commands/query

Query the Upstash Vector index and filter results based on metadata. This example uses a VectorQuery with a 'filter' string to specify conditions. It requires vector data and returns topK results that match the filter criteria.

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;

$index = new Index(
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
);

$results = $index->query(new VectorQuery(
  vector: [0.1, 0.2, ...],
  topK: 15,
  filter: "country = 'PT' AND continent = 'EU'"
));
```

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;

$index = new Index(
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
);

$results = $index->namespace('my-namespace')->query(new VectorQuery(
  vector: [0.1, 0.2, ...],
  topK: 15,
  filter: "country = 'PT' AND continent = 'EU'"
));
```

--------------------------------

### Disable Telemetry in Upstash SDK (Shell)

Source: https://upstash.com/docs/vector/sdks/ts/advanced

Opt out of sending anonymous telemetry data to improve the Upstash SDK experience. This is achieved by setting the environment variable `UPSTASH_DISABLE_TELEMETRY` to any truthy value. The example demonstrates setting this variable in a shell environment.

```shell
UPSTASH_DISABLE_TELEMETRY=1
```

--------------------------------

### Python: Perform and Fetch Resumable Query

Source: https://upstash.com/docs/vector/sdks/py/example_calls/resumable-query

Initiates a resumable nearest-neighbor search and demonstrates fetching the initial batch and subsequent results using a context manager. This is useful for paginating or streaming results incrementally.

```python
from upstash_vector import Index

index = Index()

# start a resumable query (returns initial results and a handle)
results, handle = index.resumable_query(
    vector=[0.1, 0.2],
    top_k=2,
    include_metadata=True,
    include_vectors=True,
    namespace="example-namespace",
)

with handle:
    # `results` contains the first batch
    for r in results:
        print(r.id, r.metadata, getattr(r, "vector", None))

    # fetch more results (fetch_next returns a list)
    more = handle.fetch_next(3)
    for r in more:
        print(r.id)

    # when the context block exits the handle is stopped automatically
```

--------------------------------

### Access Index Information Properties in PHP

Source: https://upstash.com/docs/vector/sdks/php/commands/info

Demonstrates how to access various properties of the `IndexInfo` object obtained from `getInfo()`. These properties provide insights into the index's state, such as the number of ready and pending vectors, index size, dimension, and similarity function. It also shows how to retrieve information for a specific namespace.

```php
// To know the number of vectors ready to query.
$info->vectorCount;

// To know the number of vectors that are getting indexed.
$info->pendingVectorCount;

// To know the size of the index in bytes.
$info->indexSize;

// To know the dimensions of your vector index.
$info->dimension;

// To know which similarity function is being used.
$info->similarityFunction;

// To get information about a specific index you can (More on next section):
$namespaceInfo = $info->namespace('my-namespace');
```

--------------------------------

### Stop a Resumable Query

Source: https://upstash.com/docs/vector/features/resumablequery

Terminates an active resumable query. This is important for managing server resources, as there's a limit to the number of concurrent resumable queries. The stop operation uses the handle obtained during the initial query. Examples are provided for Python, JavaScript, Go, and curl.

```python
handle.stop()
```

```javascript
await stop();
```

```go
handle.Close()
```

```curl
curl $UPSTASH_VECTOR_REST_URL/resumable-query-end \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  }'
```

--------------------------------

### Python: Simple Resumable Query Pagination

Source: https://upstash.com/docs/vector/sdks/py/example_calls/resumable-query

Demonstrates a simple approach to paginating results from a resumable query using a `while` loop and `fetch_next`. The handle is automatically stopped upon exiting the context manager.

```python
results, handle = index.resumable_query(vector=[0.1, 0.2], top_k=2, namespace="ns")

with handle:
    all_results = list(results)
    while True:
        next_batch = handle.fetch_next(2)
        if not next_batch:
            break
        all_results.extend(next_batch)

# handle is stopped after exiting the context manager
```

--------------------------------

### List Namespaces in Upstash Vector (Python, JavaScript, Go, PHP, cURL)

Source: https://upstash.com/docs/vector/features/namespaces

Demonstrates how to list all active namespaces in Upstash Vector. Requires the Upstash Vector client library for each respective language and API credentials (URL and Token). The output is a list of namespace names.

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.list_namespaces()
```

```javascript
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.listNamespaces()
```

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

	index.ListNamespaces()
}
```

```php
use Upstash\Vector\Index;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->listNamespaces();
```

```shell
curl $UPSTASH_VECTOR_REST_URL/list-namespaces \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

--------------------------------

### Set Request Timeout in Upstash Vector SDK (TypeScript)

Source: https://upstash.com/docs/vector/sdks/ts/advanced

Configure the Upstash Vector SDK to throw a TimeoutError if a request exceeds a specified duration. This example sets a 1-second timeout using the `AbortSignal.timeout` method within the SDK's signal parameter. It includes error handling to specifically catch and log TimeoutErrors.

```typescript
try {
  const index = new Index({
    url: "<UPSTASH_VECTOR_REST_URL>",
    token: "<UPSTASH_VECTOR_REST_TOKEN>",
    // set a timeout of 1 second
    signal: () => AbortSignal.timeout(1000),
  });
} catch (error) {
  if (error.name === "TimeoutError") {
    console.error("Request timed out");
  } else {
    console.error("An error occurred:", error);
  }
}
```

--------------------------------

### POST /resumable-query/ns

Source: https://upstash.com/docs/vector/api/endpoints/resumable-query/start-with-vector

Perform queries that can be resumed within a specific namespace.

```APIDOC
## POST /resumable-query/ns

### Description
Performs a query that can be resumed within a specified namespace, allowing results to be fetched in batches.

### Method
POST

### Endpoint
/resumable-query/ns

### Parameters
#### Query Parameters
- **namespace** (string) - Required - The namespace to query within. When no namespace is specified, the default namespace will be used.

#### Request Body
- **vector** (number[]) - Required - The query vector. Must have the same dimensions as the index.
- **topK** (number) - Optional - Defaults to 10. The number of results to return, sorted by distance score.
- **includeMetadata** (boolean) - Optional - Defaults to false. Whether to include vector metadata.
- **includeVectors** (boolean) - Optional - Defaults to false. Whether to include the vector values. Recommended to set to false to save bandwidth.
- **includeData** (boolean) - Optional - Defaults to false. Whether to include the unstructured data associated with the vectors.
- **filter** (string) - Optional - Metadata filter to apply. See [Metadata filter](/vector/features/filtering).
- **maxIdle** (number) - Optional - Maximum idle time for the resumable query in seconds.
- **weightingStrategy** (string) - Optional - For sparse/hybrid indexes, specifies the weighting strategy for querying non-zero dimensions. Possible value: `IDF`.
- **fusionAlgorithm** (string) - Optional - Fusion algorithm for hybrid indexes. Defaults to `RRF`. Other possible value: `DBSF`.

### Request Example
```sh
curl $UPSTASH_VECTOR_REST_URL/resumable-query/ns \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ \
    "vector": [0.1, 0.2], \
    "topK": 2, \
    "includeMetadata": true, \
    "maxIdle": 3600 \
  }'
```

### Response
#### Success Response (200)
- **uuid** (string) - A unique identifier for the resumable query.
- **scores** (Object[]) - An array of similarity scores for the vectors.
  - **id** (string) - The ID of the vector.
  - **score** (number) - The similarity score, based on the index's distance metric.
  - **vector** (number[]) - The dense vector value (for dense/hybrid indexes).
  - **sparseVector** (Object[]) - The sparse vector value (for sparse/hybrid indexes).
    - **indices** (number[]) - Indices of non-zero dimensions.
    - **values** (number[]) - Values of non-zero dimensions.
  - **metadata** (Object) - The metadata of the vector, if any.
  - **data** (string) - The unstructured data of the vector, if any.

#### Response Example
```json
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "scores": [
    {
      "id": "id-0",
      "score": 1.0,
      "metadata": {
        "link": "upstash.com"
      }
    },
    {
      "id": "id-1",
      "score": 0.99996454
    }
  ]
}
```
```

--------------------------------

### Access Namespace Information Properties in PHP

Source: https://upstash.com/docs/vector/sdks/php/commands/info

Shows how to access key properties of the `NamespaceInfo` object, such as the number of ready and pending vectors within that namespace. This allows for granular monitoring of vector indexing status per namespace.

```php
// To know the number of vectors ready to query.
$myNamespaceInfo->vectorCount;

// To know the number of vectors that are getting indexed.
$myNamespaceInfo->pendingVectorCount;
```

--------------------------------

### Python: Fetch Vector from Specific Namespace

Source: https://upstash.com/docs/vector/sdks/py/example_calls/fetch

This Python snippet demonstrates fetching a vector from a specific namespace within the Upstash Vector index. It highlights how to target data within a designated namespace, as opposed to the default one.

```python
index.fetch("id-4", namespace="ns")
```

--------------------------------

### Namespace Support with Upstash Semantic Cache (TypeScript)

Source: https://upstash.com/docs/vector/sdk/semantic-cache-js

Demonstrates how to use namespaces to partition data within the Upstash Semantic Cache. It initializes the Index and SemanticCache, sets a value within a specific namespace, and shows how data can be isolated.

```typescript
import { SemanticCache } from "@upstash/semantic-cache";
import { Index } from "@upstash/vector";

// 👇 your vector database
const index = new Index();

// 👇 your semantic cache
const semanticCache = new SemanticCache({ index, minProximity: 0.95, namespace: "user1" });

await semanticCache.set("Capital of Turkey", "Ankara");
```

--------------------------------

### Python Range Query with Namespace

Source: https://upstash.com/docs/vector/sdks/py/example_calls/range

Demonstrates how to specify a namespace for the 'range' query. If no namespace is provided, the default namespace is used. This allows for organizing and querying vectors within specific logical groups.

```python
index.range(..., namespace="ns")
```

--------------------------------

### Namespace Info API

Source: https://upstash.com/docs/vector/sdks/php/commands/info

Fetch information about a specific namespace within your Upstash Vector index. This includes the count of ready and pending vectors for that namespace.

```APIDOC
## GET /v1/indexes/{index_name}/namespaces/{namespace_name}

### Description
Retrieves information about a specific namespace within the Upstash Vector index, detailing the number of vectors ready for querying and those pending indexing.

### Method
GET

### Endpoint
`/v1/indexes/{index_name}/namespaces/{namespace_name}`

### Parameters
#### Path Parameters
- **index_name** (string) - Required - The name of the index.
- **namespace_name** (string) - Required - The name of the namespace.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **vectorCount** (integer) - The number of vectors ready to query in the namespace.
- **pendingVectorCount** (integer) - The number of vectors pending indexing in the namespace.

#### Response Example
```json
{
  "vectorCount": 500,
  "pendingVectorCount": 20
}
```
```

--------------------------------

### Query Upstash Vector with Text (JavaScript)

Source: https://upstash.com/docs/vector/features/hybridindexes

Shows how to query an Upstash Vector index using JavaScript. It imports the Index class, instantiates it with credentials, and executes a query using 'data' and 'topK' parameters. Assumes an asynchronous context for 'await'. Requires '@upstash/vector' package.

```JavaScript
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.query(
  {
    data: "Upstash Vector",
    topK: 1,
  },
)
```

--------------------------------

### Handling Synonyms with Upstash Semantic Cache (TypeScript)

Source: https://upstash.com/docs/vector/sdk/semantic-cache-js

Shows how the Upstash Semantic Cache can handle synonyms by retrieving the correct value even when a query uses different phrasing. It sets a value and then retrieves it using a synonymous query, demonstrating semantic understanding.

```typescript
await semanticCache.set("largest city in USA by population", "New York");
await delay(1000);

// 👇 outputs "New York"
const result = await semanticCache.get("which is the most populated city in the USA?");
```

--------------------------------

### Querying Dense and Sparse Components

Source: https://upstash.com/docs/vector/features/hybridindexes

Demonstrates how to query dense and sparse components of a hybrid index separately using the Upstash Vector client libraries.

```APIDOC
## POST /query-data

### Description
Queries a hybrid index for either dense or sparse vector components. This allows for separate retrieval of semantically similar vectors (dense) and exact query matches (sparse) before custom reranking.

### Method
POST

### Endpoint
/query-data

### Parameters
#### Query Parameters
None

#### Request Body
- **data** (string) - Required - The text data to be embedded and queried.
- **queryMode** (enum: DENSE, SPARSE) - Required - Specifies whether to query the dense or sparse component of the hybrid index.
- **topK** (integer) - Optional - The number of nearest neighbors to return.

### Request Example
```json
{
  "data": "Upstash Vector",
  "queryMode": "DENSE"
}
```

### Response
#### Success Response (200)
- **results** (array) - An array of search results, each containing:
  - **id** (string) - The ID of the vector.
  - **score** (number) - The similarity score.
  - **vector** (object) - The vector data (dense or sparse, depending on queryMode).

#### Response Example
```json
{
  "results": [
    {
      "id": "vec1",
      "score": 0.95,
      "vector": [0.1, 0.2, 0.3]
    }
  ]
}
```
```

--------------------------------

### Fetch Vectors using IDs (cURL)

Source: https://upstash.com/docs/vector/api/endpoints/fetch

Demonstrates how to fetch vectors by providing an array of their IDs and optionally including metadata using cURL. This method targets the default namespace.

```sh
curl $UPSTASH_VECTOR_REST_URL/fetch \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "ids": ["id-0"], "includeMetadata": true }'
```

--------------------------------

### Upstash Vector Index Creation and Data Operations

Source: https://upstash.com/docs/vector/features/embeddingmodels

This section details how to initialize the Upstash Vector index and perform data operations like upserting raw text data.

```APIDOC
## Initialize Upstash Vector Index

### Description
Initializes a connection to the Upstash Vector index using your REST URL and token.

### Method
Not Applicable (Client-side Initialization)

### Endpoint
Not Applicable

### Parameters
None (Configuration values are passed to the client constructor)

### Request Example (Python)
```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)
```

## Upsert Raw Text Data

### Description
Upserts raw text data into the vector index. This allows you to store and retrieve text embeddings without manual embedding generation.

### Method
POST

### Endpoint
`/upsert-data`

### Parameters
#### Request Body
- **id** (string) - Required - The unique identifier for the data entry.
- **data** (string) - Required - The raw text data to be upserted.
- **metadata** (object) - Optional - Key-value pairs for storing additional metadata associated with the data.

### Request Example (curl)
```shell
curl $UPSTASH_VECTOR_REST_URL/upsert-data \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"id": "1", "data": "Upstash is a serverless data platform.", "metadata": {"field": "value"}}'
```

### Response
#### Success Response (200)
- **`upserted`** (integer) - The number of items successfully upserted.

#### Response Example (JSON)
```json
{
  "upserted": 1
}
```
```

--------------------------------

### Perform Batch Queries with Diverse Parameters (Python)

Source: https://upstash.com/docs/vector/sdks/py/example_calls/query

Illustrates how to execute multiple queries simultaneously using the `query_many` method. This is efficient for reducing server round trips. Each query within the batch can have independent parameters for metadata, data, vectors, `top_k`, and filters.

```python
import random

from upstash_vector import Index

index = Index.from_env()

# Generate a random vector for similarity comparison
dimension = 128  # Adjust based on your index's dimension
query_vectors = [[random.random() for _ in range(dimension)] for _ in range(2)]

# Execute the query
query_results = index.query_many(
    queries=[
        {
            "vector": query_vectors[0],
            "include_metadata": True,
            "include_data": True,
            "include_vectors": False,
            "top_k": 5,
            "filter": "genre = 'fantasy' and title = 'Lord of the Rings'",
        },
        {
            "vector": query_vectors[1],
            "include_metadata": False,
            "include_data": False,
            "include_vectors": True,
            "top_k": 3,
            "filter": "genre = 'drama'",
        },
    ]
)

for i, query_result in enumerate(query_results):
    print(f"Query-{i} result:")

    # Print the query result
    for result in query_result:
        print("Score:", result.score)
        print("ID:", result.id)
        print("Vector:", result.vector)
        print("Metadata:", result.metadata)
        print("Data:", result.data)
```

--------------------------------

### Query with Distribution-Based Score Fusion (JavaScript)

Source: https://upstash.com/docs/vector/features/hybridindexes

Shows how to execute a hybrid query using DBSF in JavaScript. This code initializes the Upstash Vector client and performs a query specifying the vector, sparse vector details, and the DBSF fusion algorithm.

```javascript
import { FusionAlgorithm, Index } from "@upstash/vector";

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
});

await index.query({
  vector: [0.5, 0.4],
  sparseVector: {
    indices: [2, 3],
    values: [0.13, 0.87],
  },
  fusionAlgorithm: FusionAlgorithm.DBSF,
  topK: 3,
});
```

--------------------------------

### Perform Resumable Query with Vector

Source: https://upstash.com/docs/vector/sdks/ts/commands/resumable-query

Initiates a resumable query using a provided vector. It returns the initial results, a function to fetch more results, and a function to stop the query. Dependencies include the Upstash SDK. Inputs are query parameters like `maxIdle`, `topK`, `vector`, and flags for including metadata and vectors. Outputs are the query results and control functions.

```typescript
const { result, fetchNext, stop } = await index.resumableQuery({
    maxIdle: 3600,
    topK: 50,
    vector: [0, 1, 2, ..., 383], // 384-dimensional vector
    includeMetadata: true,
    includeVectors: true,
  });

  console.log(result);
  /*
  [
    {
      id: '6345',
      score: 1.00000012,
      vector: [0, 1, 2, ..., 383],
      metadata: {
        sentence: "Upstash is great."
      }
    },
    // ... more results
  ]
  */

  const nextBatch = await fetchNext(5); // Fetch next 5 results
  console.log(nextBatch);

  await stop(); // Stop the resumable query
```

--------------------------------

### Namespace Operations using cURL

Source: https://upstash.com/docs/vector/overall/llms-txt

Manages data within isolated namespaces in the Upstash Vector database using cURL commands. It demonstrates how to upsert data to a specific namespace, query within a namespace, and list all available namespaces. Requires UPSTASH_VECTOR_REST_URL and UPSTASH_VECTOR_REST_TOKEN.

```bash
# Upsert to namespace
curl $UPSTASH_VECTOR_REST_URL/upsert/customer-123 \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "id": "doc-1", "vector": [0.1, 0.2, 0.3, 0.4] }'

# Query namespace
curl $UPSTASH_VECTOR_REST_URL/query/customer-123 \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "vector": [0.1, 0.2, 0.3, 0.4], "topK": 5 }'

# List all namespaces
curl $UPSTASH_VECTOR_REST_URL/list-namespaces \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

--------------------------------

### POST /resumable-query

Source: https://upstash.com/docs/vector/api/endpoints/resumable-query/start-with-vector

Perform queries that can be resumed to fetch additional results. This is useful for large result sets or implementing pagination.

```APIDOC
## POST /resumable-query

### Description
Performs a query that can be resumed, allowing results to be fetched in batches. This is ideal for large datasets or paginated results.

### Method
POST

### Endpoint
/resumable-query

### Parameters
#### Query Parameters
- **namespace** (string) - Optional - The namespace to use. If not specified, the default namespace is used.

#### Request Body
- **vector** (number[]) - Required - The query vector. Must have the same dimensions as the index.
- **topK** (number) - Optional - Defaults to 10. The number of results to return, sorted by distance score.
- **includeMetadata** (boolean) - Optional - Defaults to false. Whether to include vector metadata.
- **includeVectors** (boolean) - Optional - Defaults to false. Whether to include the vector values. Recommended to set to false to save bandwidth.
- **includeData** (boolean) - Optional - Defaults to false. Whether to include the unstructured data associated with the vectors.
- **filter** (string) - Optional - Metadata filter to apply. See [Metadata filter](/vector/features/filtering).
- **maxIdle** (number) - Optional - Maximum idle time for the resumable query in seconds.
- **weightingStrategy** (string) - Optional - For sparse/hybrid indexes, specifies the weighting strategy for querying non-zero dimensions. Possible value: `IDF`.
- **fusionAlgorithm** (string) - Optional - Fusion algorithm for hybrid indexes. Defaults to `RRF`. Other possible value: `DBSF`.

### Request Example
```sh
curl $UPSTASH_VECTOR_REST_URL/resumable-query \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ \
    "vector": [0.1, 0.2], \
    "topK": 2, \
    "includeMetadata": true, \
    "maxIdle": 3600 \
  }'
```

### Response
#### Success Response (200)
- **uuid** (string) - A unique identifier for the resumable query.
- **scores** (Object[]) - An array of similarity scores for the vectors.
  - **id** (string) - The ID of the vector.
  - **score** (number) - The similarity score, based on the index's distance metric.
  - **vector** (number[]) - The dense vector value (for dense/hybrid indexes).
  - **sparseVector** (Object[]) - The sparse vector value (for sparse/hybrid indexes).
    - **indices** (number[]) - Indices of non-zero dimensions.
    - **values** (number[]) - Values of non-zero dimensions.
  - **metadata** (Object) - The metadata of the vector, if any.
  - **data** (string) - The unstructured data of the vector, if any.

#### Response Example
```json
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "scores": [
    {
      "id": "id-0",
      "score": 1.0,
      "metadata": {
        "link": "upstash.com"
      }
    },
    {
      "id": "id-1",
      "score": 0.99996454
    }
  ]
}
```
```

--------------------------------

### Using a Namespace

Source: https://upstash.com/docs/vector/features/namespaces

Namespaces are created implicitly via upsert operations. This section shows how to upsert and query vectors within a specific namespace.

```APIDOC
## POST /upsert/namespace-name

### Description
Upserts vectors into a specified namespace. Creates the namespace if it does not exist.

### Method
POST

### Endpoint
`/upsert/<namespace-name>`

### Parameters
#### Path Parameters
- **namespace-name** (string) - Required - The name of the namespace to upsert into.

#### Request Body
- **id** (string) - Required - The unique identifier for the vector.
- **vector** (array[float]) - Required - The vector embedding.

### Request Example
```json
{
  "id": "id-0",
  "vector": [0.9215, 0.3897]
}
```

## POST /query/namespace-name

### Description
Queries vectors within a specified namespace.

### Method
POST

### Endpoint
`/query/<namespace-name>`

### Parameters
#### Path Parameters
- **namespace-name** (string) - Required - The name of the namespace to query.

#### Request Body
- **vector** (array[float]) - Required - The query vector embedding.
- **topK** (integer) - Required - The number of nearest neighbors to return.

### Request Example
```json
{
  "vector": [0.9215, 0.3897],
  "topK": 5
}
```
```

--------------------------------

### Query Vectors with Python SDK

Source: https://upstash.com/docs/vector/overall/llms-txt

Performs similarity search queries on the Upstash Vector Database using the Python SDK. Allows filtering by metadata and specifying the number of nearest neighbors to return. Can include metadata and data in the results.

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

# Query with filtering
results = index.query(
    vector=[0.15, 0.25, 0.35, 0.45],
    top_k=5,
    include_metadata=True,
    include_data=True,
    filter="category = 'docs' AND title != 'API Reference'"
)

for result in results:
    print(f"{result.id}: score={result.score}, title={result.metadata.get('title')}")
```

--------------------------------

### Perform Resumable Vector Query with Namespace (cURL)

Source: https://upstash.com/docs/vector/api/endpoints/resumable-query/start-with-vector

Executes a resumable vector query within a specific namespace using cURL. This is similar to a standard resumable query but targets a named namespace. The request includes the same core parameters.

```curl
curl $UPSTASH_VECTOR_REST_URL/resumable-query/ns \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
    "vector": [0.1, 0.2],
    "topK": 2,
    "includeMetadata": true,
    "maxIdle": 3600
  }'
```

--------------------------------

### Query Upstash Vector with Text (Python)

Source: https://upstash.com/docs/vector/features/hybridindexes

Demonstrates how to query an Upstash Vector index using Python. It initializes the index with URL and token, then performs a query with specified text data and top_k results. Requires the 'upstash_vector' library.

```Python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.query(
    data="Upstash Vector",
    top_k=5,
)
```

--------------------------------

### Query Dense and Sparse Data with Custom Reranker (Go)

Source: https://upstash.com/docs/vector/features/hybridindexes

This Go program illustrates querying dense and sparse components of a hybrid index with Upstash Vector. It separates the queries for dense and sparse vectors, providing the foundation for implementing custom reranking strategies.

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

	denseScores, err := index.QueryData(vector.QueryData{
		Data:      "Upstash Vector",
		QueryMode: vector.QueryModeDense,
	})

	sparseScores, err := index.QueryData(vector.QueryData{
		Data:      "Upstash Vector",
		QueryMode: vector.QueryModeSparse,
	})

	// Rerank dense and sparse results as you like here
}
```

--------------------------------

### Hybrid Search and Fusion Queries with Python

Source: https://upstash.com/docs/vector/overall/llms-txt

This Python code snippet demonstrates how to upsert hybrid vectors and perform queries using RRF and DBSF fusion algorithms with the upstash-vector SDK. It requires specifying the index URL and token, along with dense and sparse vector data.

```python
from upstash_vector import Index, Vector
from upstash_vector.types import SparseVector, FusionAlgorithm

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

# Upsert hybrid vectors
index.upsert(
    vectors=[
        Vector(
            id="hybrid-1",
            vector=[0.1, 0.2, 0.3, 0.4],
            sparse_vector=SparseVector([10, 25, 150], [0.8, 0.6, 0.4]),
            metadata={"title": "Hybrid Document"}
        )
    ]
)

# Query with RRF
results_rrf = index.query(
    vector=[0.15, 0.25, 0.35, 0.45],
    sparse_vector=SparseVector([10, 25], [0.9, 0.7]),
    top_k=5,
    fusion_algorithm=FusionAlgorithm.RRF,
    include_metadata=True
)

# Query with DBSF
results_dbsf = index.query(
    vector=[0.15, 0.25, 0.35, 0.45],
    sparse_vector=SparseVector([10, 25], [0.9, 0.7]),
    fusion_algorithm=FusionAlgorithm.DBSF
)
```

--------------------------------

### Fetch Vectors by ID Prefix (cURL)

Source: https://upstash.com/docs/vector/api/endpoints/fetch

Shows how to fetch vectors using a prefix for their IDs. This is useful for retrieving multiple vectors that share a common identifier prefix. It also demonstrates fetching from a specified namespace.

```sh
curl $UPSTASH_VECTOR_REST_URL/fetch/ns \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "ids": ["id-0", "id-1"], "includeMetadata": true }'
```

--------------------------------

### POST /resumable-query-data

Source: https://upstash.com/docs/vector/api/endpoints/resumable-query/start-with-data

Executes a query using text data. This endpoint allows for resuming queries and fetching additional results. It supports various parameters to customize the search and control the information returned.

```APIDOC
## POST /resumable-query-data

### Description
Executes a query using text data. This endpoint allows for resuming queries and fetching additional results. It supports various parameters to customize the search and control the information returned.

### Method
POST

### Endpoint
/resumable-query-data

### Parameters
#### Path Parameters
- **namespace** (string) - Optional - The namespace to use. When no namespace is specified, the default namespace will be used.

#### Query Parameters
None

#### Request Body
- **data** (string) - Required - The text data to be embedded and used for querying.
- **topK** (number) - Optional - The total number of the vectors that you want to receive as a query result. The response will be sorted based on the distance metric score, and at most `topK` many vectors will be returned. (default: 10)
- **includeMetadata** (boolean) - Optional - Whether to include the metadata of the vectors in the response, if any. It is recommended to set this to `true` to easily identify vectors. (default: false)
- **includeVectors** (boolean) - Optional - Whether to include the vector values in the response. It is recommended to set this to `false` as the vector values can be quite big, and not needed most of the time. (default: false)
- **includeData** (boolean) - Optional - Whether to include the data of the vectors in the response, if any. (default: false)
- **filter** (string) - Optional - Metadata filter to apply. (default: "")
- **maxIdle** (number) - Optional - Maximum idle time for the resumable query in seconds.
- **weightingStrategy** (string) - Optional - For sparse vectors of sparse and hybrid indexes, specifies what kind of weighting strategy should be used while querying the matching non-zero dimension values of the query vector with the documents. If not provided, no weighting will be used. Only possible value is `IDF` (inverse document frequency).
- **fusionAlgorithm** (string) - Optional - Fusion algorithm to use while fusing scores from dense and sparse components of a hybrid index. If not provided, defaults to `RRF` (Reciprocal Rank Fusion). Other possible value is `DBSF` (Distribution-Based Score Fusion).
- **queryMode** (string) - Optional - Query mode for hybrid indexes with Upstash-hosted embedding models. Specifies whether to run the query in only the dense index, only the sparse index, or in both. If not provided, defaults to `HYBRID`. Possible values are `HYBRID`, `DENSE`, and `SPARSE`.

### Request Example
```json
{
  "data": "Hello world",
  "topK": 2,
  "includeMetadata": true,
  "maxIdle": 3600
}
```

### Response
#### Success Response (200)
Same as Resumable Query.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Upsert Data to Upstash Vector Index (Python, JavaScript, Go, PHP, cURL)

Source: https://upstash.com/docs/vector/overall/getstarted

This snippet demonstrates how to insert or update vectors in an Upstash Vector index. It requires the index URL and token for authentication. The input is a list of vectors, each with an ID, the vector itself, and optional metadata. The output is a confirmation of the upsert operation.

```python
from upstash_vector import Index

index = Index(url="UPSTASH_VECTOR_REST_URL", token="UPSTASH_VECTOR_REST_TOKEN")

index.upsert(
  vectors=[
    ("1", [0.6, 0.8], {"field": "value"}),
  ]
)
```

```javascript
import { Index } from "@upstash/vector";

const index = new Index({
    url: "UPSTASH_VECTOR_REST_URL",
    token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.upsert({ id: "1", vector: [0.6, 0.8], metadata: {field: "value"} })
```

```go
import "github.com/upstash/vector-go"

func main() {
  index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

  index.Upsert(vector.Upsert{
	  Id:       "1",
	  Vector:   []float32{0.6, 0.8},
	  Metadata: map[string]any{"field": "value"},
  })
}
```

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorUpsert;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->upsert(new VectorUpsert(
  id: '1',
  vector: [0.6, 0.8],
  metadata: ['field' => 'value'],
));
```

```shell
curl $UPSTASH_VECTOR_REST_URL/upsert \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"id": "1", "vector": [0.6, 0.8], "metadata": {"field": "value"}}'
```

--------------------------------

### Specify Namespace for Query Operations (Python)

Source: https://upstash.com/docs/vector/sdks/py/example_calls/query

Shows how to direct query operations to a specific namespace within the Upstash Vector index. If no namespace is provided, the query will default to the primary namespace.

```python
index.query(..., namespace="ns")
```

--------------------------------

### Upserting Dense and Sparse Vectors

Source: https://upstash.com/docs/vector/features/hybridindexes

Demonstrates how to upsert both dense and sparse vectors into an Upstash Vector index using various client libraries and cURL.

```APIDOC
## POST /upsert

### Description
Upserts a list of vectors, each containing both dense and sparse vector components, into the index. Both dense and sparse vectors are required for hybrid indexes.

### Method
POST

### Endpoint
/upsert

### Parameters
#### Query Parameters
None

#### Request Body
- **vectors** (array) - Required - An array of vector objects to upsert.
  - **id** (string) - Required - The unique identifier for the vector.
  - **vector** (array[number]) - Required - The dense vector embedding.
  - **sparse_vector** (object) - Required - The sparse vector representation.
    - **indices** (array[integer]) - Required - The indices of the sparse vector.
    - **values** (array[number]) - Required - The values corresponding to the indices.

### Request Example (cURL)
```shell
curl $UPSTASH_VECTOR_REST_URL/upsert \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '[
    {"id": "id-0", "vector": [0.1, 0.5], "sparseVector": {"indices": [1, 2], "values": [0.1, 0.2]}},
    {"id": "id-1", "vector": [0.3, 0.7], "sparseVector": {"indices": [123, 44232], "values": [0.5, 0.4]}}
  ]'
```

### Response
#### Success Response (200)
An empty object `{}` is returned on successful upsert.

#### Response Example
```json
{
  "message": "OK"
}
```

#### Error Response (e.g., 400 Bad Request)
- **error** (string) - Description of the error.

#### Error Example
```json
{
  "error": "Invalid input: Both dense and sparse vectors are required for hybrid indexes."
}
```
```

--------------------------------

### Query Dense and Sparse Vectors with Custom Reranking (Go)

Source: https://upstash.com/docs/vector/features/hybridindexes

Illustrates querying dense and sparse vectors independently using the Upstash Vector Go SDK. This approach enables custom reranking of search results. The code requires the 'github.com/upstash/vector-go' library and error handling.

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

	denseScores, err := index.Query(vector.Query{
		Vector: []float32{0.5, 0.4},
	})

	sparseScores, err := index.Query(vector.Query{
		SparseVector: &vector.SparseVector{
			Indices: []int32{3, 5},
			Values:  []float32{0.3, 05},
		},
	})

	// Rerank dense and sparse results as you like here
}
```

--------------------------------

### POST /reset/all

Source: https://upstash.com/docs/vector/sdks/py/example_calls/reset

Resets all namespaces within the index, clearing all vectors and metadata from every namespace.

```APIDOC
## POST /reset/all

### Description
Resets all namespaces within the index, clearing all vectors and metadata from every namespace.

### Method
POST

### Endpoint
/reset/all

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from upstash_vector import Index
index = Index.from_env()

index.reset(all=True)
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the reset operation.

#### Response Example
```json
{
  "message": "All namespaces reset successfully."
}
```
```

--------------------------------

### Perform Resumable Vector Query (cURL)

Source: https://upstash.com/docs/vector/api/endpoints/resumable-query/start-with-vector

Executes a resumable vector query using cURL. It sends a POST request with the query vector, topK, includeMetadata, and maxIdle parameters. The response includes a UUID for the query and a list of scores.

```curl
curl $UPSTASH_VECTOR_REST_URL/resumable-query \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
    "vector": [0.1, 0.2],
    "topK": 2,
    "includeMetadata": true,
    "maxIdle": 3600
  }'
```

--------------------------------

### POST /query

Source: https://upstash.com/docs/vector/overall/llms-txt

Searches for similar vectors using approximate nearest neighbor search. Supports metadata filtering and inclusion of metadata, vectors, and raw data in the response.

```APIDOC
## POST /query

### Description
Searches for similar vectors using approximate nearest neighbor search with optional metadata filtering.

### Method
POST

### Endpoint
/query

### Parameters
#### Request Body
- **vector** (array) - Required - The query vector.
- **topK** (integer) - Required - The number of nearest neighbors to return.
- **includeMetadata** (boolean) - Optional - Whether to include metadata in the response.
- **includeVectors** (boolean) - Optional - Whether to include vectors in the response.
- **includeData** (boolean) - Optional - Whether to include raw data in the response.
- **filter** (string) - Optional - SQL-like syntax for metadata filtering.

### Request Example
```json
{
  "vector": [0.15, 0.25, 0.35, 0.45],
  "topK": 5,
  "includeMetadata": true,
  "includeVectors": false,
  "includeData": true,
  "filter": "category = \"docs\" AND title != \"API Reference\""
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the matched vector.
- **score** (float) - The similarity score.
- **metadata** (object) - Metadata associated with the vector (if `includeMetadata` is true).
- **data** (string) - Raw data associated with the vector (if `includeData` is true).
- **vector** (array) - The vector itself (if `includeVectors` is true).

#### Response Example
```json
[
  {
    "id": "doc-1",
    "score": 0.99998,
    "metadata": { "title": "Getting Started", "category": "docs" },
    "data": "Introduction to Upstash Vector"
  },
  {
    "id": "doc-2",
    "score": 0.99985,
    "metadata": { "title": "Advanced Usage", "category": "docs" }
  }
]
```
```

--------------------------------

### Query Vectors with JavaScript SDK

Source: https://upstash.com/docs/vector/overall/llms-txt

Queries the Upstash Vector Database using the JavaScript SDK for similarity search with optional metadata filtering. Supports retrieving metadata, data, and vectors. Can also perform batch queries.

```javascript
import { Index } from "@upstash/vector";

const index = new Index({
  url: process.env.UPSTASH_VECTOR_REST_URL,
  token: process.env.UPSTASH_VECTOR_REST_TOKEN,
});

// Query with metadata filtering
const results = await index.query({
  vector: [0.15, 0.25, 0.35, 0.45],
  topK: 5,
  includeMetadata: true,
  includeData: true,
  filter: "category = 'docs' AND title != 'API Reference'"
});

// Expected response
// [
//   {
//     id: "doc-1",
//     score: 0.99998,
//     metadata: { title: "Getting Started", category: "docs" },
//     data: "Introduction to Upstash Vector"
//   },
//   {
//     id: "doc-2",
//     score: 0.99985,
//     metadata: { title: "Advanced Usage", category: "docs" }
//   }
// ]

// Batch query
const batchResults = await index.query([
  { vector: [0.1, 0.2, 0.3, 0.4], topK: 3 },
  { vector: [0.2, 0.3, 0.4, 0.5], topK: 3 }
]);
```

--------------------------------

### Query API

Source: https://upstash.com/docs/vector/sdks/py/example_calls/query

Retrieves vectors from the index based on similarity to a reference vector. Supports various parameters for fine-tuning the query and customizing the response.

```APIDOC
## POST /query

### Description
Retrieves vectors from the index based on similarity to a reference vector. Supports various parameters for fine-tuning the query and customizing the response.

### Method
POST

### Endpoint
/query

### Parameters
#### Query Parameters
- **vector** (array) - Required - The reference vector for similarity comparison.
- **sparse_vector** (object) - Optional - The sparse vector value to query.
- **data** (string) - Optional - A string for text-based queries (mutually exclusive with vector).
- **include_metadata** (boolean) - Optional - Indicates whether to include metadata in the query results.
- **include_vector** (boolean) - Optional - Indicates whether to include vectors in the query results.
- **include_data** (boolean) - Optional - Indicates whether to include data in the query results.
- **top_k** (integer) - Required - The number of top matching vectors to retrieve.
- **filter** (string) - Optional - Metadata filtering of the vector is used to query your data based on the filters and narrow down the query results.
- **namespace** (string) - Optional - The namespace to use. When not specified, the default namespace is used.
- **weighting_strategy** (string) - Optional - Weighting strategy to be used for sparse vectors.
- **fusion_algorithm** (string) - Optional - Fusion algorithm to use while fusing scores from hybrid vectors.
- **query_mode** (string) - Optional - Query mode for hybrid indexes with Upstash-hosted embedding models.

### Request Example
```python
import random

from upstash_vector import Index

index = Index.from_env()

dimension = 128
query_vector = [random.random() for _ in range(dimension)]

query_result = index.query(
    vector=query_vector,
    include_metadata=True,
    include_data=True,
    include_vectors=False,
    top_k=5,
    filter="genre = 'fantasy' and title = 'Lord of the Rings'",
    namespace="ns"
)

for result in query_result:
    print("Score:", result.score)
    print("ID:", result.id)
    print("Metadata:", result.metadata)
    print("Data:", result.data)
```

### Response
#### Success Response (200)
- **id** (string) - The identifier associated with the matching vector.
- **metadata** (object) - Additional information or attributes linked to the matching vector.
- **score** (float) - A measure of similarity indicating how closely the vector matches the query vector. The score is normalized to the range [0, 1], where 1 indicates a perfect match.
- **vector** (array) - The vector itself (included only if `include_vector` is set to `True`).
- **sparse_vector** (object) - The sparse vector itself (included only if `include_vector` is set to `True`).
- **data** (string) - Additional unstructured information linked to the matching vector.

#### Response Example
```json
[
  {
    "id": "vec1",
    "score": 0.95,
    "metadata": {"genre": "fantasy", "title": "Lord of the Rings"},
    "vector": [0.1, 0.2, ...],
    "data": "First book in the series"
  }
]
```
```

--------------------------------

### Upsert and Query Raw Text using JavaScript

Source: https://upstash.com/docs/vector/overall/llms-txt

Upserts raw text data into an Upstash Vector index configured with an embedding model and then queries the index using raw text. This JavaScript code uses the `@upstash/vector` package and requires environment variables for URL and token. It demonstrates adding text data with metadata and performing a similarity search, returning matching text data.

```javascript
import { Index } from "@upstash/vector";

const index = new Index({
  url: process.env.UPSTASH_VECTOR_REST_URL,
  token: process.env.UPSTASH_VECTOR_REST_TOKEN,
});

// Upsert raw text (requires index with embedding model)
await index.upsert([
  {
    id: "text-1",
    data: "Upstash is a serverless data platform for Redis and Kafka.",
    metadata: { source: "homepage", language: "en" }
  },
  {
    id: "text-2",
    data: "Vector databases store high-dimensional embeddings for similarity search.",
    metadata: { source: "docs", language: "en" }
  }
]);

// Query with raw text
const results = await index.query({
  data: "What is Upstash?",
  topK: 3,
  includeMetadata: true,
  includeData: true
});

// Returns text data with results
results.forEach(r => console.log(`${r.id}: ${r.data}`));
```

--------------------------------

### Upsert Vectors with JavaScript SDK

Source: https://upstash.com/docs/vector/overall/llms-txt

Upserts single or multiple vectors into the Upstash Vector Database using the JavaScript SDK. Requires environment variables for URL and Token. Supports optional metadata and data fields.

```javascript
import { Index } from "@upstash/vector";

const index = new Index({
  url: process.env.UPSTASH_VECTOR_REST_URL,
  token: process.env.UPSTASH_VECTOR_REST_TOKEN,
});

// Upsert single vector
await index.upsert({
  id: "doc-1",
  vector: [0.1, 0.2, 0.3, 0.4],
  metadata: { title: "Getting Started", category: "docs" },
  data: "Introduction to Upstash Vector"
});

// Upsert multiple vectors
await index.upsert([
  { id: "doc-2", vector: [0.2, 0.3, 0.4, 0.5], metadata: { title: "Advanced Usage" } },
  { id: "doc-3", vector: [0.3, 0.4, 0.5, 0.6], metadata: { title: "API Reference" } }
]);

// Expected response
// "Success"
```

--------------------------------

### Implement Reciprocal Rank Fusion (RRF) in Go

Source: https://upstash.com/docs/vector/features/hybridindexes

This Go code snippet shows how to perform a hybrid search query using Reciprocal Rank Fusion (RRF) with the Upstash Vector Go client. It initializes the index and makes a query call, providing both a dense vector and sparse vector information, and setting the fusion algorithm to RRF.

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

	scores, err := index.Query(vector.Query{
		Vector: []float32{0.5, 0.4},
		SparseVector: &vector.SparseVector{
			Indices: []int32{3, 5},
			Values:  []float32{0.3, 05},
		},
		FusionAlgorithm: vector.FusionAlgorithmRRF,
	})
}
```

--------------------------------

### Query Vectors with Metadata Filtering (Python, JavaScript, Go, PHP, cURL)

Source: https://upstash.com/docs/vector/features/metadata

Demonstrates how to query for vectors based on a provided vector and apply metadata filters. This operation requires the vector endpoint URL, token, the query vector, and optionally parameters for topK results and metadata inclusion. Filtering is done using a GLOB pattern on the 'url' metadata.

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

await index.query({
    vector: [0.9215, 0.3897],
    topK: 5,
    includeMetadata: true,
    filter: "url GLOB '*imgur.com*'",
})
```

```javascript
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.query({
  vector: [0.9215, 0.3897],
  topK: 5,
  includeMetadata: true,
  filter: "url GLOB '*imgur.com*'",
})
```

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex("UPSTASH_VECTOR_REST_URL", "UPSTASH_VECTOR_REST_TOKEN")

	index.Query(vector.Query{
		Vector:          []float32{0.9215, 0.3897},
		TopK:            5,
		IncludeMetadata: true,
		Filter:          "url GLOB '*imgur.com*'",
	})
}
```

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->query(new VectorQuery(
  vector: [0.9215, 0.3897],
  topK: 5,
  includeMetadata: true,
  filter: "url GLOB '*imgur.com*'",
));
```

```shell
curl $UPSTASH_VECTOR_REST_URL/query \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{
       "vector":[0.9215,0.3897],
       "topK" : 5,
       "includeMetadata": true,
       "filter": "url GLOB \"*imgur.com*\""
    }'
```

--------------------------------

### Perform Resumable Query with Data

Source: https://upstash.com/docs/vector/sdks/ts/commands/resumable-query

Initiates a resumable query using a text-based data input. This method is useful for semantic search when a vector is not directly available. It returns initial results, a function to fetch subsequent results, and a function to terminate the query. Dependencies include the Upstash SDK. Inputs include query parameters and the `data` field. Outputs are the query results and control functions.

```typescript
const { result, fetchNext, stop } = await index.resumableQuery({
    maxIdle: 3600,
    topK: 50,
    data: "lord of the rings"
    includeMetadata: true,
    includeData: true,
  });

  console.log(result);
  /*
  [
    {
      id: '6345',
      score: 1.00000012,
      data: "hobbit",
      metadata: {
        sentence: "Upstash is great."
      }
    },
    // ... more results
  ]
  */

  const nextBatch = await fetchNext(5); // Fetch next 5 results
  console.log(nextBatch);

  await stop(); // Stop the resumable query
```

--------------------------------

### Namespace Operations API

Source: https://upstash.com/docs/vector/overall/llms-txt

Manage and interact with namespaces within a single index. Supports upserting, querying, and listing namespaces.

```APIDOC
## Namespace Operations

### Description
Operations for managing and querying data within specific namespaces of an index.

### Method
POST / PUT / GET

### Endpoints
- **/upsert/[namespace]**: Upserts data into a specific namespace.
- **/query/[namespace]**: Queries data within a specific namespace.
- **/list-namespaces**: Lists all available namespaces.

### Parameters
#### Upsert Namespace Parameters
- **namespace** (string) - Path Parameter - The name of the namespace.
- **Request Body**:
  - **id** (string) - Required - The ID of the vector.
  - **vector** (array) - Required - The vector embedding.
  - **metadata** (object) - Optional - Metadata for the vector.

#### Query Namespace Parameters
- **namespace** (string) - Path Parameter - The name of the namespace.
- **Request Body**:
  - **vector** (array) - Required - The query vector.
  - **topK** (integer) - Required - The number of nearest neighbors to return.
  - **includeMetadata** (boolean) - Optional - Whether to include metadata.
  - **includeData** (boolean) - Optional - Whether to include raw data.

### Request Examples
#### Upsert to namespace
```bash
curl $UPSTASH_VECTOR_REST_URL/upsert/customer-123 \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "id": "doc-1", "vector": [0.1, 0.2, 0.3, 0.4] }'
```

#### Query namespace
```bash
curl $UPSTASH_VECTOR_REST_URL/query/customer-123 \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "vector": [0.1, 0.2, 0.3, 0.4], "topK": 5 }'
```

#### List all namespaces
```bash
curl $UPSTASH_VECTOR_REST_URL/list-namespaces \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

### Response
#### Success Response (200)
- **Upsert/Query**: Returns the upserted/queried data according to the operation.
- **List Namespaces**: An array of namespace names.

#### Response Example (List Namespaces)
```json
[
  "customer-123",
  "another-namespace"
]
```
```

--------------------------------

### POST /fetch/{namespace}

Source: https://upstash.com/docs/vector/api/endpoints/fetch

Fetches vectors from a specific namespace by providing an array of their IDs. You can optionally include metadata, vector values, and data in the response.

```APIDOC
## POST /fetch/{namespace}

### Description
Fetches vectors from a specific namespace by their IDs. You can optionally include metadata, vector values, and data in the response.

### Method
POST

### Endpoint
/fetch/{namespace}

### Parameters
#### Path Parameters
- **namespace** (string) - Required - The namespace from which to fetch vectors.

#### Request Body
- **ids** (string[]) - Required - Array of vector IDs to fetch.
- **prefix** (string) - Optional - Prefix of vector IDs to fetch. Limits to 1000 results.
- **includeMetadata** (boolean) - Optional - Whether to include the metadata of the vectors. Defaults to `false`.
- **includeVectors** (boolean) - Optional - Whether to include the vector values. Defaults to `false`.
- **includeData** (boolean) - Optional - Whether to include the data of the vectors. Defaults to `false`.

### Request Example
```sh
curl $UPSTASH_VECTOR_REST_URL/fetch/ns \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "ids": ["id-0", "id-1"], "includeMetadata": true }'
```

### Response
#### Success Response (200)
- **result** (Object[]) - Array of vectors, in the same order as the provided IDs. Elements can be null if no vector exists for that ID.
  - **id** (string) - Required - The ID of the vector.
  - **vector** (number[]) - The dense vector value.
  - **sparseVector** (Object[]) - The sparse vector value.
    - **indices** (number[]) - Indices of non-zero dimensions.
    - **values** (number[]) - Values of non-zero dimensions.
  - **metadata** (Object) - The metadata of the vector.
  - **data** (string) - The unstructured data of the vector.

#### Response Example
```json
{
    "result": [
        {
            "id": "id-0",
            "metadata": {
                "link": "upstash.com"
            }
        },
        {
            "id": "id-1"
        }
    ]
}
```
```

--------------------------------

### POST /resumable-query-next

Source: https://upstash.com/docs/vector/features/resumablequery

Fetches the next batch of similar vectors from a resumable query using its handle. You can call this multiple times to iterate through the entire index.

```APIDOC
## POST /resumable-query-next

### Description
Retrieves the next batch of results for an ongoing resumable query. This endpoint is useful for iterating through large result sets without loading everything into memory at once.

### Method
POST

### Endpoint
/resumable-query-next

#### Query Parameters
None

#### Request Body
- **uuid** (string) - Required - The unique identifier for the resumable query.
- **additionalK** (integer) - Optional - The number of additional nearest neighbors to fetch in this batch. Defaults to the initial `top_k` value.

### Request Example
```json
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "additionalK": 3
}
```

### Response
#### Success Response (200)
- **array** (object) - An array of similarity score objects, each containing vector data and optionally metadata.

#### Response Example
```json
[
  {
    "id": "vector1",
    "score": 0.95,
    "metadata": { "key": "value" }
  },
  {
    "id": "vector2",
    "score": 0.90,
    "metadata": { "key": "value" }
  }
]
```
```

--------------------------------

### Upsert and Query Raw Text using Python

Source: https://upstash.com/docs/vector/overall/llms-txt

Upserts raw text data into an Upstash Vector index and then queries it using text. This Python script utilizes the `upstash_vector` library and requires the database URL and token. It automatically embeds the provided text data and performs a similarity search, returning results that include the data and metadata.

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

# Upsert text data (automatically embedded)
index.upsert(
    vectors=[
        ("text-1", "Upstash is a serverless data platform.", {"source": "homepage"}),
        ("text-2", "Vector databases enable semantic search.", {"source": "docs"}),
    ]
)

# Query with text
results = index.query(
    data="What is Upstash?",
    top_k=3,
    include_data=True,
    include_metadata=True
)

for result in results:
    print(f"{result.id}: {result.data}")
```

--------------------------------

### Paginate through Vectors using JavaScript

Source: https://upstash.com/docs/vector/overall/llms-txt

Iterates through all vectors in the Upstash Vector database using JavaScript. It handles pagination using cursors and accumulates all vectors. This method requires the `@upstash/vector` package and environment variables for URL and token. It logs the total number of vectors found and demonstrates filtering by prefix.

```javascript
import { Index } from "@upstash/vector";

const index = new Index({
  url: process.env.UPSTASH_VECTOR_REST_URL,
  token: process.env.UPSTASH_VECTOR_REST_TOKEN,
});

// Iterate through all vectors
let cursor = "0";
const allVectors = [];

while (cursor !== "") {
  const result = await index.range({
    cursor,
    limit: 100,
    includeMetadata: true,
    includeData: false
  });

  allVectors.push(...result.vectors);
  cursor = result.nextCursor;
}

console.log(`Total vectors: ${allVectors.length}`);

// Range with prefix filter
const docsVectors = await index.range({
  cursor: "0",
  limit: 50,
  prefix: "doc-",
  includeMetadata: true
});
```

--------------------------------

### Python: Fetch Vectors by ID Prefix

Source: https://upstash.com/docs/vector/sdks/py/example_calls/fetch

This Python snippet illustrates fetching multiple vectors from an Upstash Vector index based on a common ID prefix. It's useful for retrieving groups of vectors that share a naming convention. A warning is noted for large datasets, suggesting the `range` command to avoid timeouts.

```python
index.fetch(prefix="id-")
```

--------------------------------

### Query with Distribution-Based Score Fusion (PHP)

Source: https://upstash.com/docs/vector/features/hybridindexes

Illustrates how to perform a hybrid query using DBSF in PHP. This snippet initializes the Upstash Vector index and constructs a query object specifying the vector, sparse vector, and the DBSF fusion algorithm.

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;
use Upstash\Vector\SparseVector;
use Upstash\Vector\Enums\FusionAlgorithm;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->query(new VectorQuery(
  vector: [0.5, 0.4],
  sparseVector: new SparseVector(
    indices: [3, 5],
    values: [0.3, 0.5],
  ),
  topK: 5,
  includeMetadata: true,
  fusionAlgorithm: FusionAlgorithm::DISTRIBUTION_BASED_SCORE_FUSION,
));
```

--------------------------------

### Paginate through Vectors using Python

Source: https://upstash.com/docs/vector/overall/llms-txt

Paginates through all vectors in the Upstash Vector database using Python. This script uses the `upstash_vector` library and requires the vector database URL and token. It collects all vectors and prints the total count. It also demonstrates retrieving results with metadata included.

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

# Paginate through all vectors
cursor = "0"
all_vectors = []

while cursor:
    result = index.range(
        cursor=cursor,
        limit=100,
        include_metadata=True
    )
    all_vectors.extend(result.vectors)
    cursor = result.next_cursor

print(f"Total vectors: {len(all_vectors)}")
```

--------------------------------

### Fetch Random Vector with Namespace (curl)

Source: https://upstash.com/docs/vector/api/endpoints/fetch-random

This snippet demonstrates fetching a random vector from a specific namespace using curl. It requires the UPSTASH_VECTOR_REST_URL and UPSTASH_VECTOR_REST_TOKEN environment variables. The request targets the /random/ns endpoint, implying namespace selection.

```curl
curl $UPSTASH_VECTOR_REST_URL/random/ns \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN"
```

--------------------------------

### Query Data from Upstash Vector (PHP)

Source: https://upstash.com/docs/vector/features/metadata

This PHP snippet shows how to query data from Upstash Vector. It initializes the Index, creates a DataQuery object with search parameters, and then iterates through the results, printing each as an array. Requires the Upstash PHP SDK.

```php
use Upstash\Vector\Index;
use Upstash\Vector\DataQuery;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$results = $index->queryData(new DataQuery(
  data: 'Upstash is a serverless data platform.',
  topK: 3,
  includeData: true,
));

foreach ($results as $result) {
  print_r($result->toArray());
}
```

--------------------------------

### Query Data API

Source: https://upstash.com/docs/vector/api/endpoints/query-data

This API endpoint allows you to query for similar vectors based on provided data. It supports single queries, queries within a namespace, and batch queries.

```APIDOC
## POST /query-data

### Description
Queries for similar vectors based on provided data. Can be used for single queries or batch queries.

### Method
POST

### Endpoint
`/query-data`

### Parameters
#### Query Parameters
None

#### Request Body
Can be a single JSON object representing a query or an array of JSON objects for batch queries.

- **data** (string) - Required - The textual data to use for querying.
- **topK** (number) - Required - The number of top similar vectors to return.
- **includeMetadata** (boolean) - Optional - Whether to include metadata in the response.
- **includeVectors** (boolean) - Optional - Whether to include dense vector values in the response.
- **includeSparseValues** (boolean) - Optional - Whether to include sparse vector values in the response.

### Request Example
```json
{
  "data": "What is Upstash?",
  "topK": 2,
  "includeMetadata": true
}
```

### Batch Request Example
```json
[
  {
    "data": "What is Upstash?",
    "topK": 2,
    "includeMetadata": true
  },
  {
    "data": "What is Upstash Vector?",
    "topK": 3
  }
]
```

### Response
#### Success Response (200)
An object containing a 'result' array. Each item in the array represents a similar vector found.

- **result** (Array<Object>) - An array of similar vectors.
  - **id** (string) - The id of the vector.
  - **score** (number) - The similarity score.
  - **vector** (number[]) - Optional - The dense vector value (for dense/hybrid indexes).
  - **sparseVector** (Object) - Optional - The sparse vector value (for sparse/hybrid indexes).
    - **indices** (number[]) - Indices of non-zero dimensions.
    - **values** (number[]) - Values of non-zero dimensions.
  - **metadata** (Object) - Optional - The metadata associated with the vector.
  - **data** (string) - Optional - The original textual data of the vector.

#### Response Example
```json
{
    "result": [
        {
            "id": "id-0",
            "score": 1.0,
            "metadata": {
                "link": "upstash.com"
            }
        },
        {
            "id": "id-1",
            "score": 0.99996454
        }
    ]
}
```

#### Error Response (422)
Returned when the index does not support embedding.

- **error** (string) - Description of the error.
- **status** (number) - The HTTP status code (422).

#### Error Response Example
```json
{
    "error": "Embedding data for this index is not allowed. The index must be created with an embedding model to use it.",
    "status": 422
}
```
```

```APIDOC
## POST /query-data/ns

### Description
Queries for similar vectors within a specific namespace.

### Method
POST

### Endpoint
`/query-data/ns`

### Parameters
#### Query Parameters
None

#### Request Body
Similar to the `/query-data` endpoint, but operates within a specified namespace.

- **data** (string) - Required - The textual data to use for querying.
- **topK** (number) - Required - The number of top similar vectors to return.
- **includeMetadata** (boolean) - Optional - Whether to include metadata in the response.
- **includeVectors** (boolean) - Optional - Whether to include dense vector values in the response.
- **includeSparseValues** (boolean) - Optional - Whether to include sparse vector values in the response.

### Request Example
```json
{
  "data": "What is Upstash?",
  "topK": 2,
  "includeMetadata": true
}
```

### Response
#### Success Response (200)
Similar to the `/query-data` endpoint, returns an object with a 'result' array of similar vectors.

#### Response Example
```json
{
    "result": [
        {
            "id": "id-0",
            "score": 1.0,
            "metadata": {
                "link": "upstash.com"
            }
        },
        {
            "id": "id-1",
            "score": 0.99996454
        }
    ]
}
```

#### Error Response (422)
Returned when the index does not support embedding.

#### Error Response Example
```json
{
    "error": "Embedding data for this index is not allowed. The index must be created with an embedding model to use it.",
    "status": 422
}
```
```

--------------------------------

### Basic Semantic Retrieval with Upstash Semantic Cache (TypeScript)

Source: https://upstash.com/docs/vector/sdk/semantic-cache-js

Illustrates a basic semantic retrieval operation using the Upstash Semantic Cache. It sets a key-value pair and then retrieves the value using a semantically similar query. A delay is included to ensure the index is updated.

```typescript
await semanticCache.set("Capital of France", "Paris");
await delay(1000);

// 👇 outputs "Paris"
const result = await semanticCache.get("What's the capital of France?");
```

--------------------------------

### Sparse Vector Operations API

Source: https://upstash.com/docs/vector/overall/llms-txt

Perform operations using sparse vectors, ideal for exact token matching, full-text search, and BM25-style retrieval.

```APIDOC
## Sparse Vector Operations

### Description
This section details operations involving sparse vectors, which are useful for keyword-based searches and combining with other retrieval methods.

### Upsert Sparse Vectors

#### Method
POST

#### Endpoint
/upsert

#### Request Body
An array of objects, where each object represents a sparse vector to be upserted.
- **id** (string) - Required - The unique identifier for the vector.
- **sparseVector** (object) - Required - An object containing the sparse vector data.
  - **indices** (array of integers) - Required - The indices of the non-zero values in the sparse vector.
  - **values** (array of floats) - Required - The values corresponding to the indices.

#### Request Example
```bash
curl $UPSTASH_VECTOR_REST_URL/upsert \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '[
    {"id": "sparse-1", "sparseVector": {"indices": [1, 42, 1523], "values": [0.3, 0.8, 0.5]}},
    {"id": "sparse-2", "sparseVector": {"indices": [5, 100, 2048], "values": [0.6, 0.4, 0.7]}}
  ]'
```

### Query Sparse Vectors

#### Method
POST

#### Endpoint
/query

#### Parameters
#### Request Body
- **sparseVector** (object) - Required - The sparse vector to use for the query.
  - **indices** (array of integers) - Required - The indices of the non-zero values.
  - **values** (array of floats) - Required - The values corresponding to the indices.
- **topK** (integer) - Required - The number of nearest neighbors to return.
- **weightingStrategy** (string) - Optional - The weighting strategy to use (e.g., "IDF").

#### Request Example
```bash
curl $UPSTASH_VECTOR_REST_URL/query \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"sparseVector": {"indices": [1, 42], "values": [0.5, 0.9]}, "topK": 3, "weightingStrategy": "IDF"}'
```

### Response
#### Success Response (200)
- **results** (array) - An array of search results, each containing an ID and score.

#### Response Example
(No specific response body example provided in the documentation)
```

--------------------------------

### Query Hybrid Indexes with Upstash Vector SDK (PHP)

Source: https://upstash.com/docs/vector/sdks/php/commands/query

Query vectors from Upstash Vector for Hybrid indexes using the SDK. This method combines dense and sparse vector querying within a `VectorQuery` object, accepting both `vector` and `sparseVector` parameters, along with `topK`. This allows for combined search capabilities.

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;
use Upstash\Vector\SparseVector;

$index = new Index(
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
);

$results = $index->query(new VectorQuery(
  vector: [0.1, 0.2, ...],
  sparseVector: new SparseVector(
    indices: [1, 2, 3],
    values: [5.0, 6.0, 7.0],
  ),
  topK: 15,
));
```

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;
use Upstash\Vector\SparseVector;

$index = new Index(
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
);

$results = $index->namespace('my-namespace')->query(new VectorQuery(
  vector: [0.1, 0.2, ...],
  sparseVector: new SparseVector(
    indices: [1, 2, 3],
    values: [5.0, 6.0, 7.0],
  ),
  topK: 15,
));
```

--------------------------------

### Querying Dense and Sparse Components for Custom Reranking

Source: https://upstash.com/docs/vector/features/hybridindexes

Demonstrates how to query the dense and sparse components of a hybrid index independently using various SDKs and cURL, enabling custom reranking of the results.

```APIDOC
## Querying Dense and Sparse Components

### Description
This endpoint allows you to query the dense and sparse vectors independently. This is useful when you want to apply custom reranking logic to the results, combining them as needed.

### Method
`POST`

### Endpoint
`/query`

### Parameters
#### Query Parameters
None

#### Request Body
**For Dense Query:**
- **vector** (array[float]) - Required - The dense vector to query with.
- **topK** (integer) - Optional - The number of results to return.

**For Sparse Query:**
- **sparseVector** (object) - Required - The sparse vector to query with.
  - **indices** (array[integer]) - Required - The indices of the sparse vector.
  - **values** (array[float]) - Required - The values of the sparse vector.
- **topK** (integer) - Optional - The number of results to return.

### Request Example (Python)
```python
from upstash_vector import Index
from upstash_vector.types import SparseVector

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

dense_results = index.query(
    vector=[0.5, 0.4],
)

sparse_results = index.query(
    sparse_vector=SparseVector([3, 5], [0.3, 0.5]),
)

# Rerank dense and sparse results as you like here
```

### Request Example (JavaScript)
```javascript
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

const denseResults = await index.query({
  vector: [0.5, 0.4],
  topK: 3,
})

const sparseResults = await index.query({
  sparseVector: {
    indices: [2, 3],
    values: [0.13, 0.87],
  },
  topK: 3,
})

// Rerank dense and sparse results as you like here
```

### Request Example (Go)
```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

	denseScores, err := index.Query(vector.Query{
		Vector: []float32{0.5, 0.4},
	})

	sparseScores, err := index.Query(vector.Query{
		SparseVector: &vector.SparseVector{
			Indices: []int32{3, 5},
			Values:  []float32{0.3, 05},
		},
	})

	// Rerank dense and sparse results as you like here
}
```

### Request Example (PHP)
```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorQuery;
use Upstash\Vector\SparseVector;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$denseResults = $index->query(new VectorQuery(
  vector: [0.5, 0.4],
  topK: 3,
));

$sparseResults = $index->query(new VectorQuery(
  sparseVector: new SparseVector(
    indices: [3, 5],
    values: [0.3, 0.5],
  ),
  topK: 3,
));

// Rerank dense and sparse results as you like here
```

### Request Example (cURL)
```bash
curl $UPSTASH_VECTOR_REST_URL/query \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"vector": [0.5, 0.4]}'

curl $UPSTASH_VECTOR_REST_URL/query \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"sparseVector": {"indices": [3, 5], "values": [0.3, 0.5]}}'
```

### Response
#### Success Response (200)
- **results** (array) - An array of query results, each containing:
  - **id** (string) - The ID of the vector.
  - **vector** (array[float]) - The vector data.
  - **score** (float) - The similarity score.
  - **metadata** (object) - Optional metadata associated with the vector.

#### Response Example
```json
{
  "results": [
    {
      "id": "vec1",
      "vector": [0.5, 0.4],
      "score": 0.95,
      "metadata": {"key": "value"}
    }
  ]
}
```

#### Error Response (400/500)
- **error** (string) - A message describing the error.

#### Error Response Example
```json
{
  "error": "Invalid input provided."
}
```
```

--------------------------------

### Different Contexts with Upstash Semantic Cache (TypeScript)

Source: https://upstash.com/docs/vector/sdk/semantic-cache-js

Shows how the Upstash Semantic Cache can differentiate between contexts even with similar keywords. It sets two distinct key-value pairs and retrieves them using queries that rely on the surrounding context to fetch the correct information.

```typescript
await semanticCache.set("the chemical formula for water", "H2O");
await semanticCache.set("the healthiest drink on a hot day", "water");

await delay(1000);

// 👇 outputs "water"
const result = await semanticCache.get("what should i drink when it's hot outside?");

// 👇 outputs "H2O"
const result = await semanticCache.get("tell me water's chemical formula");
```

--------------------------------

### POST /query

Source: https://upstash.com/docs/vector/api/endpoints/query

Queries the vector database to find the most similar vectors to a given query vector. Supports single queries, queries within a namespace, and batch queries.

```APIDOC
## POST /query

### Description
Queries the vector database to find the most similar vectors to a given query vector. This endpoint can handle single queries, queries within a specified namespace, or batch queries.

### Method
POST

### Endpoint
/query

### Parameters
#### Query Parameters
- **vector** (number[]) - Required - The query vector.
- **topK** (number) - Required - The number of nearest neighbors to return.
- **includeMetadata** (boolean) - Optional - Whether to include metadata in the response.
- **includeVectors** (boolean) - Optional - Whether to include dense vectors in the response.
- **includeSparseVectors** (boolean) - Optional - Whether to include sparse vectors in the response.

#### Request Body
Can be a single JSON object representing a query, or an array of JSON objects for batch queries.

**Single Query Object:**
- **vector** (number[]) - Required - The query vector.
- **topK** (number) - Required - The number of nearest neighbors to return.
- **includeMetadata** (boolean) - Optional - Whether to include metadata in the response.
- **includeVectors** (boolean) - Optional - Whether to include dense vectors in the response.
- **includeSparseVectors** (boolean) - Optional - Whether to include sparse vectors in the response.

**Batch Query Array:**
An array where each element is a single query object as described above.

### Request Example
**Single Query:**
```sh
curl $UPSTASH_VECTOR_REST_URL/query \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "vector": [0.1, 0.2], "topK": 2, "includeMetadata": true }'
```

**Batch Query:**
```sh
curl "$UPSTASH_VECTOR_REST_URL/query" \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '[
        {
          "vector": [0.1, 0.2],
          "topK": 2,
          "includeMetadata": true
        },
        {
          "vector": [0.2, 0.3],
          "topK": 3
        }
      ]'
```

### Response
#### Success Response (200)
An object or an array of objects containing similarity scores and optionally vector data, metadata, and sparse vectors.

**Fields:**
- **id** (string) - The id of the vector.
- **score** (number) - The similarity score.
- **vector** (number[]) - The dense vector value (if requested).
- **sparseVector** (Object[]) - The sparse vector value (if requested).
  - **indices** (number[]) - Indices of non-zero dimensions.
  - **values** (number[]) - Values of non-zero dimensions.
- **metadata** (Object) - The metadata of the vector (if requested).
- **data** (string) - The unstructured data of the vector (if available).

#### Response Example
```json
{
    "result": [
        {
            "id": "id-0",
            "score": 1.0,
            "metadata": {
                "link": "upstash.com"
            }
        },
        {
            "id": "id-1",
            "score": 0.99996454
        }
    ]
}
```
```

--------------------------------

### Query API Endpoint

Source: https://upstash.com/docs/vector/sdks/ts/commands/query

This endpoint allows you to query the vector index for the most similar vectors. You can specify the query vector, the number of results, and whether to include additional information like metadata or the vectors themselves.

```APIDOC
## POST /query

### Description
Retrieves the most similar vectors from the index using the specified distance metric and query options.

### Method
POST

### Endpoint
/query

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **vector | sparseVector | data** (number[] | SparseVector | string) - Required - The query data/vector that you want to search for in the index. Can be a vector, sparse vector, or data to be embedded.
- **topK** (number) - Required - The total number of vectors to return, sorted by similarity score.
- **includeMetadata** (boolean) - Optional - Whether to include the metadata of the vectors in the response.
- **includeVectors** (boolean) - Optional - Whether to include the vector data itself in the response.
- **includeData** (boolean) - Optional - Whether to include the original data field in the response.
- **filter** (string) - Optional - Metadata filtering string to narrow down query results.
- **weightingStrategy** (WeightingStrategy) - Optional - Weighting strategy for sparse vectors.
- **fusionAlgorithm** (FusionAlgorithm) - Optional - Fusion algorithm for hybrid indexes. Defaults to RRF.
- **queryMode** (QueryMode) - Optional - Query mode for hybrid indexes. Defaults to HYBRID.
- **Namespace** (string) - Optional - The namespace to query within. Defaults to the default namespace.

### Request Example
```json
{
  "vector": [0.1, 0.2, 0.3],
  "topK": 5,
  "includeMetadata": true,
  "includeVectors": false
}
```

### Response
#### Success Response (200)
- **result** (Array<object>) - An array of similar vectors, each containing score, vector, metadata, etc. as per request options.
  - **score** (number) - The similarity score (0-1).
  - **vector** (number[]) - The vector data (if includeVectors is true).
  - **metadata** (object) - The metadata associated with the vector (if includeMetadata is true).
  - **id** (string) - The ID of the vector.

#### Response Example
```json
{
  "result": [
    {
      "score": 0.95,
      "id": "vec1",
      "metadata": {"key": "value"},
      "vector": [0.11, 0.22, 0.33]
    }
  ]
}
```
```

--------------------------------

### Batch Query API

Source: https://upstash.com/docs/vector/sdks/py/example_calls/query

Performs a batch of queries in a single call to eliminate round trips to the server. Each query in the batch can have its own parameters.

```APIDOC
## POST /query_many

### Description
Performs a batch of queries in a single call to eliminate round trips to the server. Each query in the batch can have its own parameters.

### Method
POST

### Endpoint
/query_many

### Parameters
#### Request Body
- **queries** (array) - Required - An array of query objects, where each object contains the parameters for a single query.
  - **vector** (array) - Required - The reference vector for similarity comparison.
  - **sparse_vector** (object) - Optional - The sparse vector value to query.
  - **data** (string) - Optional - A string for text-based queries (mutually exclusive with vector).
  - **include_metadata** (boolean) - Optional - Indicates whether to include metadata in the query results.
  - **include_vector** (boolean) - Optional - Indicates whether to include vectors in the query results.
  - **include_data** (boolean) - Optional - Indicates whether to include data in the query results.
  - **top_k** (integer) - Required - The number of top matching vectors to retrieve.
  - **filter** (string) - Optional - Metadata filtering of the vector is used to query your data based on the filters and narrow down the query results.
  - **namespace** (string) - Optional - The namespace to use. When not specified, the default namespace is used.
  - **weighting_strategy** (string) - Optional - Weighting strategy to be used for sparse vectors.
  - **fusion_algorithm** (string) - Optional - Fusion algorithm to use while fusing scores from hybrid vectors.
  - **query_mode** (string) - Optional - Query mode for hybrid indexes with Upstash-hosted embedding models.

### Request Example
```python
import random

from upstash_vector import Index

index = Index.from_env()

dimension = 128
query_vectors = [[random.random() for _ in range(dimension)] for _ in range(2)]

query_results = index.query_many(
    queries=[
        {
            "vector": query_vectors[0],
            "include_metadata": True,
            "include_data": True,
            "include_vectors": False,
            "top_k": 5,
            "filter": "genre = 'fantasy' and title = 'Lord of the Rings'",
        },
        {
            "vector": query_vectors[1],
            "include_metadata": False,
            "include_data": False,
            "include_vectors": True,
            "top_k": 3,
            "filter": "genre = 'drama'",
            "namespace": "ns"
        },
    ]
)

for i, query_result in enumerate(query_results):
    print(f"Query-{i} result:")
    for result in query_result:
        print("Score:", result.score)
        print("ID:", result.id)
        print("Vector:", result.vector)
        print("Metadata:", result.metadata)
        print("Data:", result.data)
```

### Response
#### Success Response (200)
- **results** (array of arrays) - An array where each element is the result of a corresponding query in the batch. Each inner array contains objects with the following fields:
  - **id** (string) - The identifier associated with the matching vector.
  - **metadata** (object) - Additional information or attributes linked to the matching vector.
  - **score** (float) - A measure of similarity indicating how closely the vector matches the query vector. The score is normalized to the range [0, 1], where 1 indicates a perfect match.
  - **vector** (array) - The vector itself (included only if `include_vector` is set to `True`).
  - **sparse_vector** (object) - The sparse vector itself (included only if `include_vector` is set to `True`).
  - **data** (string) - Additional unstructured information linked to the matching vector.

#### Response Example
```json
[
  [
    {
      "id": "vec1",
      "score": 0.95,
      "metadata": {"genre": "fantasy", "title": "Lord of the Rings"},
      "vector": [0.1, 0.2, ...],
      "data": "First book in the series"
    }
  ],
  [
    {
      "id": "vec2",
      "score": 0.88,
      "vector": [0.3, 0.4, ...]
    }
  ]
]
```
```

--------------------------------

### Fetch Vectors by ID or Prefix using JavaScript

Source: https://upstash.com/docs/vector/overall/llms-txt

Retrieve vectors using the Upstash Vector JavaScript SDK. This function allows fetching vectors by providing an array of IDs or a prefix string. Options to include metadata and vectors in the result are available. The prefix fetch returns up to 1000 vectors.

```javascript
import { Index } from "@upstash/vector";

const index = new Index({
  url: process.env.UPSTASH_VECTOR_REST_URL,
  token: process.env.UPSTASH_VECTOR_REST_TOKEN,
});

// Fetch by IDs
const vectors = await index.fetch(["doc-1", "doc-2"], {
  includeMetadata: true,
  includeVectors: true
});

// Fetch by prefix (returns up to 1000 vectors)
const prefixVectors = await index.fetch({
  prefix: "doc-",
  includeMetadata: true
});

// Expected response
// [
//   {
//     id: "doc-1",
//     vector: [0.1, 0.2, 0.3, 0.4],
//     metadata: { title: "Getting Started", category: "docs" },
//     data: "Introduction to Upstash Vector"
//   },
//   {
//     id: "doc-2",
//     vector: [0.2, 0.3, 0.4, 0.5],
//     metadata: { title: "Advanced Usage", category: "docs" }
//   }
// ]
```

--------------------------------

### Query with Distribution-Based Score Fusion (Python)

Source: https://upstash.com/docs/vector/features/hybridindexes

Demonstrates how to perform a hybrid query using Distribution-Based Score Fusion (DBSF) in Python. It initializes the Upstash Vector index and calls the query method with a dense vector, a sparse vector, and the DBSF fusion algorithm.

```python
from upstash_vector import Index
from upstash_vector.types import FusionAlgorithm, SparseVector

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.query(
    vector=[0.5, 0.4],
    sparse_vector=SparseVector([3, 5], [0.3, 0.5]),
    fusion_algorithm=FusionAlgorithm.DBSF,
)
```

--------------------------------

### Query Upstash Vector with Text (PHP)

Source: https://upstash.com/docs/vector/features/hybridindexes

Illustrates querying an Upstash Vector index with PHP. It utilizes the Upstash\Vector\Index class, initializing it with URL and token. The queryData method is used with a DataQuery object specifying text, topK, and metadata inclusion. Requires the Upstash PHP SDK.

```PHP
use Upstash\Vector\Index;
use Upstash\Vector\DataQuery;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->queryData(new DataQuery(
  data: 'Upstash Vector',
  topK: 5,
  includeMetadata: true,
));
```

--------------------------------

### Upsert Dense and Sparse Vectors in Upstash Vector

Source: https://upstash.com/docs/vector/features/hybridindexes

Demonstrates how to upsert both dense and sparse vectors into an Upstash Vector index. This is crucial for hybrid indexing, requiring both vector types for each entry. It shows implementations in Python, JavaScript, Go, PHP, and cURL.

```python
from upstash_vector import Index, Vector
from upstash_vector.types import SparseVector

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.upsert(
    vectors=[
        Vector(id="id-0", vector=[0.1, 0.5], sparse_vector=SparseVector([1, 2], [0.1, 0.2])),
        Vector(id="id-1", vector=[0.3, 0.7], sparse_vector=SparseVector([123, 44232], [0.5, 0.4])),
    ]
)
```

```javascript
import { Index } from "@upstash/vector"

const index = new Index({
  url: "UPSTASH_VECTOR_REST_URL",
  token: "UPSTASH_VECTOR_REST_TOKEN",
})

await index.upsert([{
  id: 'id-0',
  vector: [0.1, 0.5],
  sparseVector: {
    indices: [2, 3],
    values: [0.13, 0.87],
  },
}])
```

```go
package main

import (
	"github.com/upstash/vector-go"
)

func main() {
	index := vector.NewIndex(
		"UPSTASH_VECTOR_REST_URL",
		"UPSTASH_VECTOR_REST_TOKEN",
	)

	err := index.UpsertMany([]vector.Upsert{
		{
			Id:     "id-0",
			Vector: []float32{0.1, 0.5},
			SparseVector: &vector.SparseVector{
				Indices: []int32{1, 2},
				Values:  []float32{0.1, 0.2},
			},
		},
		{
			Id:     "id-1",
			Vector: []float32{0.3, 0.7},
			SparseVector: &vector.SparseVector{
				Indices: []int32{123, 44232},
				Values:  []float32{0.5, 0.4},
			},
		},
	})
}
```

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorUpsert;
use Upstash\Vector\SparseVector;

use function Upstash\Vector\createRandomVector;

$index = new Index(
  url: 'UPSTASH_VECTOR_REST_URL',
  token: 'UPSTASH_VECTOR_REST_TOKEN',
);

$index->upsert(new VectorUpsert(
  id: 'id-0',
  vector: createRandomVector(384),
  sparseVector: new SparseVector(
    indices: [1, 2, 3],
    values: [5, 6, 7],
  ),
));
```

```shell
curl $UPSTASH_VECTOR_REST_URL/upsert \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '[
    {"id": "id-0", "vector": [0.1, 0.5], "sparseVector": {"indices": [1, 2], "values": [0.1, 0.2]}},
    {"id": "id-1", "vector": [0.3, 0.7], "sparseVector": {"indices": [123, 44232], "values": [0.5, 0.4]}}
  ]'
```

--------------------------------

### Query with DBSF Fusion using cURL

Source: https://upstash.com/docs/vector/overall/llms-txt

This cURL command demonstrates how to query the Upstash Vector database using the DBSF (Distribution-Based Score Fusion) algorithm for hybrid search. It requires the Upstash Vector REST URL and token, along with dense and sparse vectors for the query.

```bash
curl $UPSTASH_VECTOR_REST_URL/query \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"vector": [0.15, 0.25, 0.35], "sparseVector": {"indices": [10], "values": [0.9]}, "fusionAlgorithm": "DBSF"}'
```

--------------------------------

### POST /query/ns

Source: https://upstash.com/docs/vector/api/endpoints/query

Queries a specific namespace within the vector database to find the most similar vectors to a given query vector.

```APIDOC
## POST /query/ns

### Description
Queries a specific namespace within the vector database to find the most similar vectors to a given query vector. This is useful for organizing and querying data within distinct partitions.

### Method
POST

### Endpoint
/query/ns

### Parameters
#### Query Parameters
- **vector** (number[]) - Required - The query vector.
- **topK** (number) - Required - The number of nearest neighbors to return.
- **includeMetadata** (boolean) - Optional - Whether to include metadata in the response.
- **includeVectors** (boolean) - Optional - Whether to include dense vectors in the response.
- **includeSparseVectors** (boolean) - Optional - Whether to include sparse vectors in the response.

#### Request Body
```json
{
  "vector": [0.1, 0.2],
  "topK": 2,
  "includeMetadata": true
}
```

### Request Example
```sh
curl $UPSTASH_VECTOR_REST_URL/query/ns \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "vector": [0.1, 0.2], "topK": 2, "includeMetadata": true }'
```

### Response
#### Success Response (200)
An object or an array of objects containing similarity scores and optionally vector data, metadata, and sparse vectors.

**Fields:**
- **id** (string) - The id of the vector.
- **score** (number) - The similarity score.
- **vector** (number[]) - The dense vector value (if requested).
- **sparseVector** (Object[]) - The sparse vector value (if requested).
  - **indices** (number[]) - Indices of non-zero dimensions.
  - **values** (number[]) - Values of non-zero dimensions.
- **metadata** (Object) - The metadata of the vector (if requested).
- **data** (string) - The unstructured data of the vector (if available).

#### Response Example
```json
{
    "result": [
        {
            "id": "id-0",
            "score": 1.0,
            "metadata": {
                "link": "upstash.com"
            }
        },
        {
            "id": "id-1",
            "score": 0.99996454
        }
    ]
}
```
```

--------------------------------

### Implement Reciprocal Rank Fusion (RRF) in Python

Source: https://upstash.com/docs/vector/features/hybridindexes

This Python snippet demonstrates how to perform a query using Reciprocal Rank Fusion (RRF) with Upstash Vector. It shows initializing the index and calling the query method with both a dense vector and a sparse vector, explicitly setting the fusion algorithm to RRF.

```python
from upstash_vector import Index
from upstash_vector.types import FusionAlgorithm, SparseVector

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

index.query(
    vector=[0.5, 0.4],
    sparse_vector=SparseVector([3, 5], [0.3, 0.5]),
    fusion_algorithm=FusionAlgorithm.RRF,
)
```

--------------------------------

### Fetch Vectors by ID or Prefix using Python

Source: https://upstash.com/docs/vector/overall/llms-txt

Retrieve vectors using the Upstash Vector Python SDK. This method allows fetching specific vectors by ID or retrieving vectors that match a given prefix. The function accepts parameters to include metadata along with the vector data.

```python
from upstash_vector import Index

index = Index(
    url="UPSTASH_VECTOR_REST_URL",
    token="UPSTASH_VECTOR_REST_TOKEN",
)

# Fetch specific vectors
vectors = index.fetch(
    ids=["doc-1", "doc-2"],
    include_metadata=True,
    include_vectors=True
)

# Fetch by prefix
prefix_vectors = index.fetch(
    prefix="doc-",
    include_metadata=True
)
```

--------------------------------

### Complex Queries with Upstash Semantic Cache (TypeScript)

Source: https://upstash.com/docs/vector/sdk/semantic-cache-js

Illustrates how to handle complex queries using the Upstash Semantic Cache. It sets a specific piece of information and then retrieves it using a query that rephrases the request, showcasing the cache's ability to understand nuanced questions.

```typescript
await semanticCache.set("year in which the Berlin wall fell", "1989");
await delay(1000);

// 👇 outputs "1989"
const result = await semanticCache.get("what's the year the Berlin wall destroyed?");
```

--------------------------------

### Upsert Data Many

Source: https://upstash.com/docs/vector/sdks/php/commands/upsert-data

Efficiently upsert multiple data points at once, with the SDK generating vector embeddings for each. Supports batch upserts with or without specifying a namespace.

```APIDOC
## POST /upsertDataMany

### Description
Upserts multiple data points in a single request, automatically generating vector embeddings for each using an embedding model. Supports batch upserts with or without specifying a namespace.

### Method
POST

### Endpoint
/upsertDataMany

### Parameters
#### Query Parameters
- **namespace** (string) - Optional - The namespace to upsert the data into.

#### Request Body
- **items** (array) - Required - An array of data objects to upsert.
  - Each item in the array should have:
    - **id** (string) - Required - The unique identifier for the data point.
    - **data** (string) - Required - The text data to be vectorized and upserted.

### Request Example
```json
{
  "items": [
    { "id": "1", "data": "The capital of Japan is Tokyo" },
    { "id": "2", "data": "The capital of France is Paris" },
    { "id": "3", "data": "The capital of Germany is Berlin" }
  ]
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "success": true
}
```
```