### Install and Start Flowise

Source: https://upstash.com/docs/vector/integrations/flowise

Commands to install the Flowise package globally using npm and launch the application server locally.

```bash
npm install -g flowise
```

```bash
npx flowise start
```

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

### Install Dependencies (bun)

Source: https://upstash.com/docs/vector/integrations/ai-sdk

Installs the necessary packages for the AI SDK and Upstash Vector using bun.

```bash
bun install @ai-sdk/openai ai zod @upstash/vector
```

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

### Install upstash-vector SDK

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

Install the upstash-vector SDK using pip.

```APIDOC
## Install upstash-vector SDK

### Description
Install the upstash-vector SDK using pip.

### Method
N/A (Shell Command)

### Endpoint
N/A

### Parameters
None

### Request Example
```bash
pip install upstash-vector
```

### Response
N/A
```

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

### Install Dependencies (npm)

Source: https://upstash.com/docs/vector/integrations/ai-sdk

Installs the necessary packages for the AI SDK and Upstash Vector using npm.

```bash
npm install @ai-sdk/openai ai zod @upstash/vector
```

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

### Install Bun Runtime

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

Installs the Bun runtime environment, which is required for dependency management and project scripts.

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

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

### Install Dependencies (pnpm)

Source: https://upstash.com/docs/vector/integrations/ai-sdk

Installs the necessary packages for the AI SDK and Upstash Vector using pnpm.

```bash
pnpm install @ai-sdk/openai ai zod @upstash/vector
```

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

### Install Upstash Vector SDKs

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

Commands to install the Upstash Vector SDK using npm, pnpm, pip, or Composer.

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

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

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

```shell
pip install upstash-vector
```

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

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

### Install Upstash Vector SDK

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

Commands to install the @upstash/vector package using npm or pnpm package managers.

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

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

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

### Install Upstash Semantic Cache and Vector Packages

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

This snippet shows the npm command to install the necessary Upstash packages for semantic caching and vector database integration. It requires Node.js and npm to be installed.

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

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

### Environment Variables Setup

Source: https://upstash.com/docs/vector/integrations/ai-sdk

Sets up the required environment variables for OpenAI API key and Upstash Vector credentials in the .env file.

```bash
OPENAI_API_KEY=your_openai_api_key
UPSTASH_VECTOR_REST_URL=your_upstash_url
UPSTASH_VECTOR_REST_TOKEN=your_upstash_token
```

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

### Install Upstash Vector and LangChain Libraries

Source: https://upstash.com/docs/vector/tutorials/langchain

This command installs the necessary Python packages for interacting with Upstash Vector and LangChain, including the Upstash-specific LangChain integration.

```bash
pip install upstash-vector python-dotenv langchain langchain-community
```

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

### Start Resumable Query using cURL

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

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 \
  }'
```

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

### Install Upstash Vector Python SDK

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

This snippet shows the command to install the upstash-vector Python SDK using pip. This is the first step to using the SDK in your Python project.

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

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

### Install Dependencies

Source: https://upstash.com/docs/vector/tutorials/huggingface-embeddings

Installs the necessary Python libraries for using LangChain, Hugging Face embeddings, and Upstash Vector. This includes langchain, sentence-transformers, upstash-vector, python-dotenv, langchain-community, and langchain-huggingface.

```bash
pip install langchain sentence_transformers upstash-vector python-dotenv langchain-community langchain-huggingface
```

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

### Install Upstash Vector and LangChain dependencies

Source: https://upstash.com/docs/vector/integrations/langchain

Install the required Python packages including upstash-vector, langchain, langchain-community, and python-dotenv to enable integration.

```bash
pip install upstash-vector langchain langchain-community python-dotenv
```

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

### Python Full Index Scan Example

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

This Python code demonstrates how to scan the entire Upstash Vector index by iteratively calling the `range` method. It starts with an empty cursor and continues fetching results using the `next_cursor` until all vectors are retrieved. The example shows how to print vectors in batches.

```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)
```

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

### Initiate a Resumable Vector Query

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

Demonstrates how to start a resumable query across different languages. Each implementation returns a result set and a handle or fetch function to continue the query process.

```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)
```

```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);
}
```

```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)
	}
}
```

```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
  }'
```

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

### Install Dependencies for RAG App

Source: https://upstash.com/docs/vector/tutorials/gradio-application

Command to install all required Python libraries for the RAG application, including Gradio, LangChain, and Upstash Vector support.

```bash
pip install gradio langchain sentence_transformers upstash-vector python-dotenv transformers langchain-community langchain-huggingface
```

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

### Install Upstash Vector SDK

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

Use Composer to install the Upstash Vector PHP SDK into your project. This is the primary method for managing dependencies for the library.

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

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

### Install Langflow and Upstash Vector

Source: https://upstash.com/docs/vector/integrations/langflow

Install the necessary libraries for Langflow and Upstash Vector integration. This command installs both packages using pip, making them available for local use in your Python environment.

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

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

### Fetch Vectors with ID Prefix

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

This code example shows how to use the range method with a prefix to filter vectors by their IDs. It retrieves vectors whose IDs start with the specified prefix, along with a limit and starting cursor. The response contains the next cursor and the filtered list of vectors.

```typescript
const responseRange = await index.range({
    cursor: 0,
    limit: 2,
    prefix: "test-",
  });

  /*
  {
    nextCursor: '2',
    vectors: [
      { id: 'test-1' },
      { id: 'test-2' },
    ]
  }
  */
```

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

### Install Upstash Vector and Python Dotenv

Source: https://upstash.com/docs/vector/tutorials/semantic_search

Installs the 'upstash-vector' library for interacting with Upstash Vector and 'python-dotenv' for loading environment variables from a .env file. This is a prerequisite for the semantic search script.

```bash
pip install upstash-vector python-dotenv
```

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

### Range Vectors via REST API

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

Demonstrates how to fetch a range of vectors using the REST API. The first example targets the default namespace, while the second example demonstrates scoping to a specific namespace.

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

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

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

### Reset Namespace Response Example (JSON)

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

This is an example of a successful response when resetting a namespace in Upstash Vector. It indicates the operation was successful with a 'Success' string.

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

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

### Fetch Vectors by ID Prefix (Python)

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

Demonstrates fetching all vectors whose IDs start with a given prefix. This is useful for retrieving a group of related vectors. A warning is included for large datasets, recommending the `range` command to avoid timeouts.

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

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

### Install Dependencies for LlamaParse and Upstash Vector

Source: https://upstash.com/docs/vector/integrations/llamaparse

Installs the necessary Python packages for using LlamaParse, Upstash Vector, and managing environment variables. This includes llama-index, upstash-vector, and python-dotenv.

```bash
pip install llama-index upstash-vector llama-index-vector-stores-upstash python-dotenv
```

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

### Query Data with PHP SDK

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

Shows how to query an index using raw text strings which are automatically converted to embeddings. Includes examples for standard queries and namespace-scoped queries.

```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,
  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,
  includeData: true,
));
```

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

### Query Vectors with Metadata Filters

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

Demonstrates how to perform a vector similarity search with a metadata filter applied. This example shows the implementation across multiple languages including Python, JavaScript, Go, PHP, and 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'",
));
```

```shell
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
}'
```

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

### Install Upstash Vector Laravel SDK

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

Install the Upstash Vector Laravel SDK using Composer. This is the first step to integrating Upstash Vector into your Laravel application.

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

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

### Start Resumable Query - JavaScript

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

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.

```APIDOC
## Start Resumable Query - JavaScript

### Description
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.

### Method
POST

### Endpoint
N/A (SDK specific)

### Parameters
N/A (SDK specific)

### Request Example
```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);
}
```

### Response
N/A (SDK specific)
```

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

### GET /fetch/{namespace}

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

Fetches multiple vectors by their IDs from a specified namespace.

```APIDOC
## GET /fetch/{namespace}

### Description
Retrieves multiple vectors that share a common identifier prefix or specific IDs from a namespace.

### Method
POST

### Endpoint
/fetch/{namespace}

### Parameters
#### Path Parameters
- **namespace** (string) - Required - The target namespace.

#### Request Body
- **ids** (array) - Required - List of vector IDs to fetch.
- **includeMetadata** (boolean) - Optional - Whether to return metadata.

### Request Example
```json
{ "ids": ["id-0", "id-1"], "includeMetadata": true }
```

### Response
#### Success Response (200)
- **result** (array) - List of fetched vector objects.
```

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

### Setup Upstash Credentials for Semantic Cache

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

This snippet demonstrates how to set up environment variables for your Upstash Vector database URL and token. These credentials are required to connect the semantic cache to your database. Ensure you have created an Upstash Vector database and selected an embedding model.

```env
UPSTASH_VECTOR_REST_URL=https://example.upstash.io
UPSTASH_VECTOR_REST_TOKEN=your_secret_token_here
```

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

### Query Vectors Using Textual Data

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

Illustrates how to perform a query using textual data as input and retrieve associated vector data. This example shows how to include the 'data' field in the query results.

```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
})
```

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

### Environment Variables Setup

Source: https://upstash.com/docs/vector/tutorials/llamaindex

This snippet shows how to set up environment variables for Upstash Vector and OpenAI API keys. It loads variables from a .env file, which is a common practice for managing sensitive information in Python applications.

```bash
UPSTASH_VECTOR_REST_URL=your_upstash_url
UPSTASH_VECTOR_REST_TOKEN=your_upstash_token
OPENAI_API_KEY=your_openai_api_key
```

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

### Perform Hybrid Query with Distribution-Based Score Fusion

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

Example of executing a hybrid search in Go using the DBSF fusion algorithm with sparse and dense vectors.

```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,
	})
}
```

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

### Initialize Upstash Vector Client

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

Demonstrates how to initialize the Index client. You can either load credentials from the environment or pass them manually to the constructor.

```php
use Upstash\Vector\Index;

// Initialize from environment variables
$index = Index::fromEnv();

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

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

### Start Resumable Query - Python and Go

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

Initiates a resumable nearest neighbor search using the Upstash Vector SDKs. 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. The Go version returns scores and a handle, while the Python version returns results and a handle.

```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)
```

```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)
	}
}
```

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

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

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

Provides an example of a hybrid query using DBSF (Distribution-Based Score Fusion) in Go. It demonstrates setting up the Upstash Vector index client and making a query request that includes both dense and sparse vectors, along with the DBSF fusion algorithm.

```APIDOC
## Query with Distribution-Based Score Fusion

### Description
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.

### Method
POST

### Endpoint
/query (Implicitly via SDK)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **Vector** (array) - Required - The dense vector embedding.
- **SparseVector** (object) - Optional - The sparse vector representation.
  - **Indices** (array) - Required if SparseVector is present - Indices of the sparse vector.
  - **Values** (array) - Required if SparseVector is present - Values of the sparse vector.
- **FusionAlgorithm** (string) - Required - The fusion algorithm to use, e.g., `vector.FusionAlgorithmDBSF`.

### Request Example
```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,
	})
}
```

### Response
#### Success Response (200)
- **scores** (array) - An array of scores resulting from the hybrid query.

#### Response Example
```json
[
  0.85,
  0.72
]
```
```

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

### Upserting Vectors in TypeScript

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

Demonstrates how to upsert single or multiple vectors into an index. Includes examples for basic vector insertion and using namespaces.

```typescript
await index.upsert({
  id: "1234",
  vector: [0.1, 0.2, 0.3, 0.4, 0.5],
  metadata: {
    title: "Lord of The Rings",
    genre: "drama",
    category: "classic",
  },
});
```

```typescript
await index.upsert([
  {
    id: "6789",
    vector: [0.6, 0.7, 0.8, 0.9, 0.9],
  },
  {
    id: "1234",
    vector: [0.1, 0.2, 0.3, 0.4, 0.5],
    metadata: {
      title: "Lord of The Rings",
      genre: "drama",
      category: "classic",
    },
  },
]);
```

```typescript
await index.upsert([
  {
    id: "6789",
    vector: [0.6, 0.7, 0.8, 0.9, 0.9],
  },
], { namespace: "my-namespace" });
```

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

### GET /info

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

Retrieves metadata and metrics about the specified vector index.

```APIDOC
## GET /info

### Description
Retrieves information and metrics about the vector index.

### Method
GET

### Endpoint
$UPSTASH_VECTOR_REST_URL/info

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

### Response
#### Success Response (200)
- **index_info** (object) - Contains metrics and configuration details of the index.
```

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

### GET /random

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

Fetches a random vector from the specified or default namespace.

```APIDOC
## GET /random

### Description
Fetches a random vector from the default namespace. If no namespace is specified, the default namespace will be used.

### Method
GET

### Endpoint
/random

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

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

### Response
#### Success Response (200)
- **id** (string) - The ID of the random vector.
- **vector** (array) - The vector values.
```

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

### GET /info

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

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

```APIDOC
## GET /info

### Description
Returns metadata and configuration details about the index, including vector counts, index size, and namespace information.

### Method
GET

### Endpoint
/info

### Parameters
None

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

### Response
#### Success Response (200)
- **vectorCount** (number) - Total number of ready vectors across all namespaces.
- **pendingVectorCount** (number) - Total number of vectors currently processing.
- **indexSize** (number) - Total size of the index in bytes.
- **dimension** (number) - Dimension of the vectors.
- **similarityFunction** (string) - Similarity function used (e.g., COSINE).
- **indexType** (string) - Type of index (DENSE, SPARSE, or HYBRID).
- **denseIndex** (object) - Configuration for dense vectors.
- **sparseIndex** (object) - Configuration for sparse vectors.
- **namespaces** (object) - Map of namespace names to their respective vector counts.

#### Response Example
{
  "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
      }
    }
  }
}
```

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

### Initialize and Query Upstash Vector Store in LangChain

Source: https://upstash.com/docs/vector/integrations/langchain

Demonstrates how to initialize the UpstashVectorStore, add documents to the index, and perform a semantic similarity search using LangChain.

```python
from dotenv import load_dotenv
from langchain_community.vectorstores.upstash import UpstashVectorStore
from langchain.schema import Document

load_dotenv()

store = UpstashVectorStore(
    embedding=True,
)

documents = [
    Document(page_content="Upstash Vector is a scalable vector database."),
    Document(page_content="LangChain is a framework for building intelligent apps."),
    Document(page_content="Semantic search enables advanced query matching."),
]

store.add_documents(documents)

query = "What is LangChain?"
results = store.similarity_search(query, k=3)

print("Similarity Search Results:")
for res in results:
    print(res.page_content)
```

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

### POST /resumable-query API Endpoint Documentation

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

Initiates a new resumable query. This endpoint allows you to start a query and optionally configure parameters like `maxIdle` time. It returns an initial batch of results and a handle to continue the query.

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

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

### Initialize Upstash Vector Store with LlamaIndex

Source: https://upstash.com/docs/vector/integrations/llamaindex

Configure the UpstashVectorStore, load documents from a local directory, and create a VectorStoreIndex using a storage context.

```python
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.vector_stores.upstash import UpstashVectorStore
from llama_index.core import StorageContext
import os
from dotenv import load_dotenv

load_dotenv()

upstash_vector_store = UpstashVectorStore(
    url=os.environ["UPSTASH_VECTOR_REST_URL"],
    token=os.environ["UPSTASH_VECTOR_REST_TOKEN"],
)

documents = SimpleDirectoryReader("./documents/").load_data()
storage_context = StorageContext.from_defaults(vector_store=upstash_vector_store)
index = VectorStoreIndex.from_documents(
    documents, storage_context=storage_context
)
```

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

### Sparse Vector Representation Example

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

Demonstrates the structure of a sparse vector representation in Python, showing how non-zero values are stored with their corresponding dimension indices. This contrasts with a dense vector representation.

```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
)
```

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

### Paginate Through Vectors

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

Iterates through all vectors in the database using cursor-based pagination. Includes examples for both JavaScript and Python.

```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}`);
```

```python
from upstash_vector import Index

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

# Pagination logic
cursor = "0"
all_vectors = []
while cursor != "":
    res = index.range(cursor=cursor, limit=100, include_metadata=True)
    all_vectors.extend(res.vectors)
    cursor = res.next_cursor

print(f"Total vectors: {len(all_vectors)}")
```

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

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

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

This PHP example demonstrates querying with Reciprocal Rank Fusion (RRF) using the Upstash Vector PHP SDK. It includes initializing the index and making a query with both dense and sparse vectors, specifying 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,
));
```

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

### 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 endpoint is useful for paginating through query results.

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

### Description
Resumes a previously started query to fetch additional results. This endpoint is useful for paginating through query 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
```json
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "additionalK": 2
}
```

### Response
#### Success Response (200)
- **Scores** (Object[]) - An array of vector search results.
  - **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-id-1",
      "score": 0.95,
      "vector": [0.1, 0.2, 0.3],
      "sparseVector": {
        "indices": [1, 5, 10],
        "values": [0.5, 0.2, 0.1]
      },
      "metadata": {"key": "value"},
      "data": "example data"
    }
  ]
}
```
```

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

### Initialize and Use Semantic Cache in Node.js

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

This snippet illustrates how to initialize and use the Semantic Cache in a Node.js application. It demonstrates setting a cache entry with a key and value, and then retrieving it using a semantically similar query. It requires the '@upstash/semantic-cache' and '@upstash/vector' packages to be installed and Upstash credentials to be configured.

```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 });

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 Data API Request Examples

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

Provides JSON request bodies for performing single and batch similarity queries against the Upstash Vector REST API.

```json
{
  "data": "What is Upstash?",
  "topK": 2,
  "includeMetadata": true
}
```

```json
[
  {
    "data": "What is Upstash?",
    "topK": 2,
    "includeMetadata": true
  },
  {
    "data": "What is Upstash Vector?",
    "topK": 3
  }
]
```

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

### Upserting Raw Data in TypeScript

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

Demonstrates how to upsert raw text data into an index, which is automatically embedded by Upstash. Includes examples for single and bulk data operations.

```typescript
await index.upsert({
  id: "1234",
  data: "'The Lord of the Rings' follows Frodo Baggins and his allies on a quest to destroy a powerful ring and save Middle-earth from the dark lord Sauron.",
  metadata: {
    title: "Lord of The Rings",
    genre: "drama",
    category: "classic",
  },
});
```

```typescript
await index.upsert([
  {
    id: "6789",
    data: "'Harry Potter' follows the journey of a young wizard, Harry Potter, as he attends Hogwarts School of Witchcraft and Wizardry, forms deep friendships, and confronts the dark wizard Voldemort, who seeks immortality and domination over the magical world.",
  },
  {
    id: "1234",
    data: "'The Lord of the Rings' follows Frodo Baggins and his allies on a quest to destroy a powerful ring and save Middle-earth from the dark lord Sauron.",
    metadata: {
      title: "Lord of The Rings",
      genre: "drama",
      category: "classic",
    },
  },
]);
```

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

### POST /range

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

Retrieves a range of vectors starting from a specified cursor, allowing for efficient pagination through the dataset.

```APIDOC
## POST /range

### Description
Retrieves a range of vectors starting from a cursor until the end of the vectors or the specified limit. This is used for iterating through the entire vector store.

### Method
POST

### Endpoint
/range/{namespace}

### Parameters
#### Path Parameters
- **namespace** (string) - Optional - The namespace to use. Defaults to the default namespace.

#### Request Body
- **cursor** (string) - Required - The offset to the last retrieved vector. Use "0" for the initial request.
- **limit** (number) - Required - The maximum number of vectors to return.
- **prefix** (string) - Optional - Prefix of the vector IDs to filter by.
- **includeMetadata** (boolean) - Optional - Whether to include vector metadata. Defaults to false.
- **includeVectors** (boolean) - Optional - Whether to include the dense vector values. Defaults to false.
- **includeData** (boolean) - Optional - Whether to include the unstructured data of the vector. Defaults to false.

### Request Example
{
  "cursor": "0",
  "limit": 2,
  "includeMetadata": true
}

### Response
#### Success Response (200)
- **nextCursor** (string) - The offset for the next range request.
- **vectors** (Array) - A list of vector objects containing id, metadata, and optional vector values.

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

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

### Initialize Index Client from Environment Variables

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

Initialize the Index client for upstash-vector by automatically loading credentials from environment variables.

```APIDOC
## Initialize Index Client from Environment Variables

### Description
Initialize the Index client for upstash-vector by automatically loading credentials from environment variables.

### Method
N/A (Python Code)

### Endpoint
N/A

### Parameters
None

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

### Response
N/A
```

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

### Client Initialization

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

How to initialize the Upstash Vector client using environment variables or a configuration object.

```APIDOC
## Initialization

### Description
Initialize the Upstash Vector client to perform operations on your vector store.

### Configuration
- **UPSTASH_VECTOR_REST_URL** (string) - Required - The REST URL for your index.
- **UPSTASH_VECTOR_REST_TOKEN** (string) - Required - The REST token for your index.

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

// Using environment variables
const index = new Index();

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

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

### GET /range

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

Retrieves a range of vectors from the database, supporting pagination via cursors and optional namespace filtering.

```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
#### Path Parameters
- **namespace** (string) - Optional - The namespace to use. When no namespace is specified, the default namespace will be used.

#### 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.

### Request Example
curl $UPSTASH_VECTOR_REST_URL/range -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.
- **vectors** (Object[]) - An array of vector objects.

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

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

### Upsert Vector with Metadata

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

Example of how to upsert a vector with associated metadata into the Upstash Vector index using the Python SDK.

```APIDOC
## Upsert Vector with Metadata

### Description
Example of how to upsert a vector with associated metadata into the Upstash Vector index using the Python SDK.

### Method
N/A (Python Code)

### Endpoint
N/A

### Parameters
#### Request Body
- **vectors** (list) - Required - A list of tuples, where each tuple contains:
    - **id** (string) - The unique identifier for the vector.
    - **vector** (list[float]) - The vector data.
    - **metadata** (dict) - Optional metadata associated with the vector.

### Request Example
```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)
    ])

main()
```

### Response
#### Success Response (200)
- **ids** (list[string]) - A list of IDs of the upserted vectors.

#### Response Example
```json
{
  "ids": ["id-for-vector"]
}
```
```

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

### 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.

```APIDOC
## Sparse Vector Operations using Python

### Description
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.

### Method
POST

### Endpoint
N/A (SDK specific)

### Parameters
N/A (SDK specific)

### Request Example
```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
)
```

### Response
N/A (SDK specific)
```

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

### List Namespaces

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

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.

```APIDOC
## GET /list-namespaces

### Description
Lists all namespaces within the Upstash Vector index.

### Method
GET

### Endpoint
/list-namespaces

### Parameters
#### Query Parameters
None

#### Request Body
None

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

### Response
#### Success Response (200)
- **namespaces** (array) - An array of namespace names.

#### Response Example
```json
{
  "namespaces": ["default", "namespace1", "namespace2"]
}
```
```

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

### GET /info

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

Fetches statistical information about the vector index, including vector counts, index size, dimensions, similarity function, and namespace statistics.

```APIDOC
## GET /info

### Description
Retrieves comprehensive statistical data about the vector index. This includes the total number of vectors, pending vectors, index size, dimensionality, the chosen similarity function, and detailed statistics for each namespace.

### Method
GET

### Endpoint
/info

### Parameters
None

### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **vector_count** (integer) - The total number of vectors in the index.
- **pending_vector_count** (integer) - The number of vectors currently in a pending state.
- **index_size** (integer) - The size of the index in bytes.
- **dimension** (integer) - The dimensionality of the vectors in the index.
- **similarity_function** (string) - The similarity function used by the index (e.g., 'COSINE', 'EUCLID', 'DOT_PRODUCT').
- **namespaces** (object) - A map where keys are namespace names and values are objects containing statistics for that namespace:
  - **vector_count** (integer) - The number of vectors in the specific namespace.
  - **pending_vector_count** (integer) - The number of pending vectors in the specific namespace.

#### Response Example
```json
{
  "vector_count": 1000,
  "pending_vector_count": 0,
  "index_size": 512000,
  "dimension": 1536,
  "similarity_function": "COSINE",
  "namespaces": {
    "default": {
      "vector_count": 1000,
      "pending_vector_count": 0
    },
    "ns1": {
      "vector_count": 500,
      "pending_vector_count": 0
    }
  }
}
```
```

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

### Delete Namespace API Responses

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

Example JSON response bodies for successful namespace deletion and error handling when a namespace is not found.

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

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

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

### Initialize Upstash Vector and Embeddings

Source: https://upstash.com/docs/vector/tutorials/gradio-application

Initializes the environment, sets up Hugging Face embeddings, and connects to the Upstash Vector store.

```python
import gradio as gr
from dotenv import load_dotenv
from langchain_huggingface.embeddings import HuggingFaceEmbeddings
from langchain_community.vectorstores.upstash import UpstashVectorStore
from transformers import pipeline
from langchain.schema import Document

load_dotenv()

embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/all-mpnet-base-v2")
vector_store = UpstashVectorStore(embedding=embeddings)
```

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

### Query Dense and Sparse Vectors with Custom Reranking

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

Provides an example for querying dense and sparse vectors separately, suitable for custom reranking strategies.

```APIDOC
## POST /query

### Description
Queries dense and sparse vectors separately, allowing for custom reranking strategies.

### Method
POST

### Endpoint
/query

### Parameters
#### Request Body (Dense Query)
- **vector** (array) - Required - The dense vector to query with.
- **topK** (integer) - Required - The number of nearest neighbors to return.

#### Request Body (Sparse Query)
- **sparseVector** (object) - Required - The sparse vector to query with.
  - **indices** (array) - Required - Array of indices for the sparse vector.
  - **values** (array) - Required - Array of values for the sparse vector.
- **topK** (integer) - Required - The number of nearest neighbors to return.

### Request Example (Dense Query)
```php
$denseResults = $index->query(new VectorQuery(
  vector: [0.5, 0.4],
  topK: 3,
));
```

### Request Example (Sparse Query)
```php
$sparseResults = $index->query(new VectorQuery(
  sparseVector: new SparseVector(
    indices: [3, 5],
    values: [0.3, 0.5],
  ),
  topK: 3,
));
```

### Response
#### Success Response (200)
- **results** (array) - An array of query results.

#### Response Example
```json
{
  "results": [
    {
      "id": "id-0",
      "score": 0.85,
      "vector": [0.5, 0.4]
    }
  ]
}
```
```

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

### List Namespaces Response Example (JSON)

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

This snippet shows the expected JSON response when successfully listing namespaces from an Upstash Vector index. The response contains a 'result' field, which is an array of strings representing the names of the namespaces. An empty string denotes the default namespace.

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

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

### List Namespaces - Go

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

This Go code snippet shows how to use the vector-go package to create a new Index instance with the provided URL and token, and then call the ListNamespaces() method.

```go
package main

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

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

	index.ListNamespaces()
}
```

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

### Initialize Resumable Query with Custom Idle Timeout

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

Start a new resumable query while specifying a custom max idle time in seconds to control how long the query remains active before automatic termination.

```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
})
```

```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,
    "maxIdle": 7200
  }'
```

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

### Perform Resumable Query with Python

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

Demonstrates how to initiate a resumable query, iterate through the initial results, and fetch subsequent batches using the handle. The context manager ensures the query handle is automatically stopped after execution.

```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)
```

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

### Initialize Upstash Vector Store and LlamaIndex

Source: https://upstash.com/docs/vector/tutorials/llamaindex

This Python code initializes the Upstash Vector store using credentials from environment variables and loads documents from a local directory. It then sets up the storage context and creates a VectorStoreIndex with specified dimensions and distance metric.

```python
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.vector_stores.upstash import UpstashVectorStore
from llama_index.core import StorageContext
import openai
import os
from dotenv import load_dotenv

# Load environment variables
load_dotenv()
openai.api_key = os.environ["OPENAI_API_KEY"]

# Setup the Upstash vector store 
upstash_vector_store = UpstashVectorStore(
    url=os.environ["UPSTASH_VECTOR_REST_URL"],
    token=os.environ["UPSTASH_VECTOR_REST_TOKEN"],
)

# Read the document about global warming from the documents directory
documents = SimpleDirectoryReader("./documents/").load_data()

# Initialize the storage context with the Upstash vector store
storage_context = StorageContext.from_defaults(vector_store=upstash_vector_store)

# Create the index from the loaded document with 1536 dimensions and cosine distance
index = VectorStoreIndex.from_documents(
    documents, storage_context=storage_context
)
```

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

### Python Range Query Example

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

This Python code snippet demonstrates how to use the `range` method to retrieve vectors from an Upstash Vector index. It shows how to set parameters like cursor, limit, and include flags, and how to process the results including the next cursor and vector information (ID, vector, metadata, data).

```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)
```

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

### Implement Reciprocal Rank Fusion (RRF)

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

This 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.

```APIDOC
## POST /query (with RRF)

### Description
Executes a query using Reciprocal Rank Fusion (RRF) by combining dense and sparse vector data.

### Method
POST

### Endpoint
/query

### Parameters
#### Query Parameters
None

#### Request Body
- **vector** (array) - Required - The dense vector embedding.
- **sparseVector** (object) - Optional - An object containing `indices` (array of integers) and `values` (array of floats) for sparse vector data.
- **topK** (integer) - Required - The number of top results to return.
- **includeMetadata** (boolean) - Optional - Whether to include metadata.
- **fusionAlgorithm** (string) - Required - Set to "RRF" for Reciprocal Rank Fusion.

### Request Example
```json
{
  "vector": [0.5, 0.4],
  "sparseVector": {
    "indices": [3, 5],
    "values": [0.3, 0.5]
  },
  "topK": 5,
  "includeMetadata": true,
  "fusionAlgorithm": "RRF"
}
```

### Response
#### Success Response (200)
- **results** (array) - An array of matching vectors, potentially combined using RRF.

#### Response Example
```json
[
  {
    "id": "doc-1",
    "score": 0.9,
    "vector": [0.1, 0.2, 0.3, 0.4],
    "metadata": { "source": "file.txt" }
  }
]
```
```

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

### Fetch Random Vector

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

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. This example uses a curl command to demonstrate the API endpoint.

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

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

### Fetch Vectors via REST API

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

Demonstrates how to retrieve specific vectors by their IDs using a cURL request. The first example fetches a single vector with metadata, while the second demonstrates fetching multiple vectors within a specific namespace.

```bash
curl $UPSTASH_VECTOR_REST_URL/fetch \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "ids": ["id-0"], "includeMetadata": true }'
```

```bash
curl $UPSTASH_VECTOR_REST_URL/fetch/ns \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "ids": ["id-0", "id-1"], "includeMetadata": true }'
```

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

### Configure Environment Variables

Source: https://upstash.com/docs/vector/tutorials/llamaparse

Sets up the required environment variables in a .env file for Upstash Vector, OpenAI API, and LlamaCloud API.

```plaintext
UPSTASH_VECTOR_REST_URL=your_upstash_url
UPSTASH_VECTOR_REST_TOKEN=your_upstash_token
OPENAI_API_KEY=your_openai_api_key
LLAMA_CLOUD_API_KEY=your_llama_cloud_api_key
```

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

### Specify Command-Level Metadata Type (TypeScript)

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

Demonstrates how to specify a metadata type for a specific command, such as 'upsert', without setting it globally at the index level. This offers flexibility for commands requiring different metadata structures. The example uses TypeScript.

```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
}});
```

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

### Initialize Index Client with URL and Token

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

Initialize the Index client for upstash-vector using your Upstash Vector URL and Token.

```APIDOC
## Initialize Index Client with URL and Token

### Description
Initialize the Index client for upstash-vector using your Upstash Vector URL and Token.

### Method
N/A (Python Code)

### Endpoint
N/A

### Parameters
#### Request Body
- **url** (string) - Required - Your Upstash Vector REST URL.
- **token** (string) - Required - Your Upstash Vector REST Token.

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

### Response
N/A
```

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

### Upsert Hybrid Vectors in Upstash Vector

Source: https://upstash.com/docs/vector/sdks/php/commands/upsert-vectors

Demonstrates how to upsert a hybrid vector, which requires both a dense vector and a sparse vector. Examples include standard and namespaced upsert operations.

```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: '1',
  vector: createRandomVector(dimensions: 1536),
  sparseVector: new SparseVector(
    indices: [0, 1],
    values: [1.0, 2.0],
  ),
));
```

```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->namespace('my-namespace')->upsert(new VectorUpsert(
  id: '1',
  vector: createRandomVector(dimensions: 1536),
  sparseVector: new SparseVector(
    indices: [0, 1],
    values: [1.0, 2.0],
  ),
));
```

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

### API Response Structures

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

Example JSON responses for successful queries and error states. The successful response includes a list of results with IDs, similarity scores, and optional metadata.

```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
}
```

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

### Basic Semantic Retrieval

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

Demonstrates a basic cache set and get operation. After setting a key-value pair, it retrieves the value using a semantically similar query. A 1-second delay is included to allow the vector index to update.

```typescript
await semanticCache.set("Capital of France", "Paris");
await delay(1000);

// Retrieve the value using a semantically similar query
const result = await semanticCache.get("What's the capital of France?");
// result will be "Paris"
```

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

### Fetch Vectors with Pagination and Metadata

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

This snippet demonstrates how to use the range method to fetch vectors, including their metadata, with a specified limit and starting cursor. It also shows how to specify a namespace for the query. The response includes the next cursor for subsequent requests and the list of vectors with their IDs and metadata.

```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"
        }
      }
    ]
  }
  */
```

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

### Upsert Vectors via REST API

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

Examples of how to upsert single or multiple vectors into an Upstash Vector index using cURL. The first example demonstrates batch upserting to the default namespace, while the second shows a single vector upsert into a specific namespace.

```sh
curl $UPSTASH_VECTOR_REST_URL/upsert \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '[
    { "id": "id-0", "vector": [0.1, 0.2], "metadata": { "link": "upstash.com" } },
    { "id": "id-1", "vector": [0.2, 0.3] }
  ]'
```

```sh
curl $UPSTASH_VECTOR_REST_URL/upsert/ns \
  -X POST \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "id": "id-2", "vector": [0.1, 0.2], "metadata": { "link": "upstash.com" } }'
```

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

### Simple Resumable Query Pagination (Python)

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

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. This requires the `upstash_vector` library and an initialized index.

```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
```

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

### Initialize Upstash Vector Index Client

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

Demonstrates two ways to initialize the Upstash Vector Index client in Python. The first method uses explicit URL and token, while the second automatically loads credentials from environment variables. It's recommended to initialize the client outside request handlers in serverless environments for reuse.

```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()
```

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

### Query Vector Data via REST API

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

Examples of how to query vector data using curl. This includes standard queries, namespace-scoped queries, and batch processing of multiple queries in a single request.

```bash
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 }'
```

```bash
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 }'
```

```bash
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
        }
      ]'
```

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

### Query Upstash Vector Index by Vector Embedding

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

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.

```APIDOC
## POST /query

### Description
Queries the Upstash Vector index using a vector embedding to find similar items. Supports specifying the number of results, including metadata and vectors, and filtering by namespace.

### Method
POST

### Endpoint
/query

### Parameters
#### Query Parameters
None

#### Request Body
- **vector** (array) - Required - The vector embedding to query with.
- **topK** (integer) - Required - The number of top results to return.
- **includeMetadata** (boolean) - Optional - Whether to include metadata in the response.
- **includeVectors** (boolean) - Optional - Whether to include vectors in the response.
- **namespace** (string) - Optional - The namespace to query within.

### Request Example
```json
{
  "vector": [ ... ],
  "topK": 2,
  "includeMetadata": true,
  "includeVectors": true,
  "namespace": "my-namespace"
}
```

### Response
#### Success Response (200)
- **results** (array) - An array of matching vectors, each with id, score, vector, and metadata.

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

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

### POST /resumable-query-next

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

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.

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

### Description
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.

### Method
POST

### Endpoint
/resumable-query-next

### Parameters

#### Request Body
- **uuid** (string) - Required - The unique identifier of the initial query.
- **additionalK** (integer) - Required - The number of additional results to retrieve.

### Request Example
```json
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "additionalK": 2
}
```

### Response
#### Success Response (200)
- **results** (array of objects) - An array of additional matching vectors.

#### Response Example
```json
{
  "results": [
    {
      "id": "vec456",
      "vector": [0.4, 0.5, 0.6],
      "score": 0.88
    }
  ]
}
```

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

### Query Hybrid Index with Dense and Sparse Modes (Go)

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

Illustrates how to query both dense and sparse components of a hybrid index using the Go SDK. This pattern allows for custom reranking logic based on the returned scores.

```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,
	})
}
```

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

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

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

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)
- **Response** (IndexInfo) - An object containing index statistics and configuration.
  - **dimensions** (number) - The dimensionality of the vectors in the index.
  - **metric** (string) - The distance metric used by the index (e.g., 'cosine', 'euclidean', 'dotproduct').
  - **size** (number) - The number of vectors currently stored in the index.
  - **vector হৈing** (number) - The number of vectors currently being indexed.
  - **diskUsage** (number) - The disk space used by the index in bytes.

#### Response Example
```json
{
  "dimensions": 1536,
  "metric": "cosine",
  "size": 10000,
  "vector হৈing": 0,
  "diskUsage": 52428800
}
```
```

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

### Configure Environment Variables

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

Set the required REST URL and token as environment variables to allow the SDK to automatically detect your configuration.

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

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

### Upsert API Response Examples

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

JSON representations of successful and failed API responses for the upsert operation. These illustrate the standard 'Success' result and potential error handling for invalid vector dimensions.

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

```json
{
  "error": "Invalid vector dimension: 2, expected: 256",
  "status": 422
}
```

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

### Manage Namespaces and Operations (Python)

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

Illustrates namespace management, data upsertion, querying, listing, and deleting namespaces using the Upstash Vector Python SDK. It requires initializing the Index with URL and token.

```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")
```

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

### Semantic Cache API

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

This section details the core functionalities of the Semantic Cache, including setting and retrieving cached data based on semantic similarity. It requires an Upstash Vector database and specific environment variables for setup.

```APIDOC
## Semantic Cache API

### Description
Provides functionalities to cache and retrieve data based on semantic similarity, enabling efficient handling of natural language queries and AI responses. It leverages an Upstash Vector database for storing and querying data embeddings.

### Method
POST, GET (Implied by usage)

### Endpoint
`/` (Internal to the library)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **key** (string) - Required - The natural language key representing the data to be cached or retrieved.
- **value** (any) - Required - The data to be cached.
- **minProximity** (number) - Optional - The minimum similarity threshold for retrieving cached data. Defaults to 0.95.

### Request Example
```json
{
  "key": "Capital of Turkey",
  "value": "Ankara"
}
```

### Response
#### Success Response (200)
- **value** (any) - The cached value associated with a semantically similar key.

#### Response Example
```json
{
  "value": "Ankara"
}
```

## Setup and Usage

### Prerequisites
- An Upstash Vector database instance.

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

### Configuration
Create a `.env` file with your Upstash Vector credentials:
```
UPSTASH_VECTOR_REST_URL=https://your-vector-db-url.upstash.io
UPSTASH_VECTOR_REST_TOKEN=your_vector_db_token
```

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

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

// Initialize Semantic Cache
const semanticCache = new SemanticCache({ index, minProximity: 0.95 });

async function demoCache() {
  // Set a cache entry
  await semanticCache.set("Capital of Turkey", "Ankara");
  await new Promise(resolve => setTimeout(resolve, 1000)); // Simulate delay

  // Retrieve a semantically similar entry
  const result = await semanticCache.get("What is Turkey's capital?");
  console.log(result); // Output: "Ankara"
}

demoCache();
```
```

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

### Implement Pagination with Resumable Queries

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

Shows a pattern for paginating through all search results by continuously calling fetch_next until no more results are returned.

```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)
```

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

### Manage Namespaces and Perform Operations with JavaScript SDK

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

Demonstrates how to initialize the Upstash Vector JavaScript SDK, create and manage namespaces, upsert data, query within a namespace, list all namespaces, and delete a namespace. Requires UPSTASH_VECTOR_REST_URL and UPSTASH_VECTOR_REST_TOKEN environment variables.

```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");

```

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

### GET /vectors/range

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

Retrieves vectors from the index within a specified range, supporting pagination and filtering by ID prefix.

```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.
- **limit** (integer) - Optional - The maximum number of vectors to retrieve.
- **include_vectors** (boolean) - Optional - Include vector embeddings in the response.
- **include_metadata** (boolean) - Optional - Include metadata in the response.
- **include_data** (boolean) - Optional - Include data in the response.

### Response
#### Success Response (200)
- **result** (array) - A list of vector objects containing id, score, and optional metadata.
```

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

### Range Query for Data Retrieval

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

This snippet illustrates how to perform a range query on the Upstash Vector database to retrieve a subset of data. It includes examples in Python, JavaScript, Go, PHP, and curl, showing how to specify the cursor, limit, and includeMetadata options.

```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,
));
```

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

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

### Upsert Data using cURL

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

Demonstrates how to upsert single or multiple data entries into Upstash Vector using cURL. It provides examples for both the default namespace and a specified namespace. Requires UPSTASH_VECTOR_REST_URL and UPSTASH_VECTOR_REST_TOKEN environment variables.

```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" } }'

```

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

### Python Range Query with ID Prefix

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

This Python snippet illustrates how to use the `range` method with a `prefix` parameter to retrieve only those vectors whose IDs start with a specific string. This is useful for targeted retrieval of related vectors.

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

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

### GET /similarity_search

Source: https://upstash.com/docs/vector/tutorials/langchain

Performs a semantic search against the indexed documents to find the most relevant matches based on a query string.

```APIDOC
## GET /similarity_search

### Description
Queries the vector index to retrieve documents semantically similar to the provided input string.

### Method
GET

### Endpoint
/similarity_search

### Query Parameters
- **query** (string) - Required - The search string to compare against indexed vectors.
- **k** (integer) - Optional - The number of top results to return (default: 5).

### Request Example
GET /similarity_search?query=Technology's+role+in+global+warming.&k=5

### Response
#### Success Response (200)
- **results** (array) - A list of Document objects containing page_content and metadata.
```

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

### Initialize Semantic Cache with Namespace

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

This snippet shows how to initialize the Semantic Cache client, specifying an index, the `minProximity` for cache hits, and a namespace to partition data. The `minProximity` of 0.95 requires a high degree of similarity for a cache hit.

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

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

// Initialize the semantic cache with a specific namespace and minProximity
const semanticCache = new SemanticCache({ index, minProximity: 0.95, namespace: "user1" });

// Set a value in the cache
await semanticCache.set("Capital of Turkey", "Ankara");
```

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

### Format Project Code

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

Runs the project's code formatter to ensure consistent style across the codebase.

```bash
bun run fmt
```

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

### GET /random

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

Fetches a random vector from the Upstash Vector index. This endpoint is useful for sampling data or testing retrieval.

```APIDOC
## GET /random

### Description
Fetches a random vector from the Upstash Vector index. This endpoint is useful for sampling data or testing retrieval.

### Method
GET

### Endpoint
/random

### Parameters
None

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

### Response
#### Success Response (200)
- **vector** (object) - The fetched random vector, including its ID, vector data, and metadata.

#### Response Example
```json
{
  "id": "vec123",
  "vector": [0.1, 0.2, 0.3],
  "metadata": {"genre": "sci-fi"}
}
```

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

### GET /range

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

Retrieves a range of vectors from the index, supporting pagination via cursors and optional inclusion of metadata or data.

```APIDOC
## GET /range

### Description
Retrieves a list of vectors from the index. Supports pagination using cursors and allows filtering by namespace or ID prefix.

### Method
GET

### Endpoint
/range

### Parameters
#### Query Parameters
- **cursor** (string) - Optional - The cursor to start the range query from.
- **limit** (integer) - Optional - Maximum number of results to return.
- **include_vectors** (boolean) - Optional - Whether to include the vector embeddings.
- **include_metadata** (boolean) - Optional - Whether to include metadata.
- **include_data** (boolean) - Optional - Whether to include associated data.
- **namespace** (string) - Optional - The namespace to query.
- **prefix** (string) - Optional - Filter by ID prefix.

### Response
#### Success Response (200)
- **next_cursor** (string) - Cursor for the next page of results.
- **vectors** (array) - List of vector objects.

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

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

### GET /index/info

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

Retrieves statistical information about the Upstash Vector index, including vector counts, dimensions, and namespace-specific statistics.

```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) - Total number of vectors in the index.
- **pending_vector_count** (integer) - Number of vectors currently being processed.
- **index_size** (integer) - Total size of the index.
- **dimension** (integer) - Vector dimensions.
- **similarity_function** (string) - Similarity metric used.
- **namespaces** (object) - Statistics per namespace.
```

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

### Perform Resumable Vector Query using cURL

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

This example shows how to execute a resumable vector query against the Upstash Vector database using cURL. It sends a POST request to the `/resumable-query` endpoint, including the query vector, `topK` value, `includeMetadata` flag, and `maxIdle` time. The response contains 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
  }'
```

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

### REST API Response Formats

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

Examples of successful and error JSON response payloads returned by the Upstash Vector REST API.

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

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

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

### Bootstrap Next.js Application

Source: https://upstash.com/docs/vector/integrations/ai-sdk

Creates a new Next.js application with TypeScript support and navigates into the project directory.

```bash
npx create-next-app rag-chatbot --typescript
cd rag-chatbot
```

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

### Initialize Upstash Vector Index

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

Establishes a connection to the Upstash Vector index by providing the REST URL and authentication token to the client constructor.

```python
from upstash_vector import Index

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

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

### Delete Vectors by ID Prefix

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

Deletes all vectors whose IDs start with a specified prefix. Returns the count of deleted vectors.

```APIDOC
## DELETE /vectors

### Description
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.

### Method
DELETE

### Endpoint
/vectors

### Parameters
#### Query Parameters
- **prefix** (string) - Required - The prefix of the vector IDs to delete.

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

### Response
#### Success Response (200)
- **count** (integer) - The number of vectors deleted.
```

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

### Retrieve Index Information with Upstash Vector SDK

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

Demonstrates how to initialize the Upstash Vector client and retrieve comprehensive index metadata using the getInfo() method. The returned IndexInfo object provides access to vector counts, index size, and similarity function settings.

```php
use Upstash\Vector\Index;

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

$info = $index->getInfo();

// Accessing properties
$info->vectorCount;
$info->pendingVectorCount;
$info->indexSize;
$info->dimension;
$info->similarityFunction;
```

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

### GET /v1/indexes/{index_name}/namespaces/{namespace_name}

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

Retrieves metadata and vector counts for a specific namespace within an Upstash Vector index.

```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
{
  "vectorCount": 500,
  "pendingVectorCount": 20
}
```

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

### Retrieve Index Information with JavaScript SDK

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

Demonstrates how to initialize the Upstash Vector client and retrieve detailed index statistics, including vector counts, dimension, and namespace-specific 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,
});

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}`);
}

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

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

### List Namespaces (Python, JavaScript, Go, PHP, cURL)

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

Demonstrates how to list all active namespaces in Upstash Vector. Requires the Upstash Vector client library for each respective language or cURL, along with 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();
```

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

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

### Retrieve Index Information using Python SDK

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

Fetches index configuration, statistics, and namespace details using the Python SDK.

```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")
```

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

### Perform Resumable Query with Python SDK

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

Illustrates performing a resumable query for sparse or hybrid indexes using the Upstash Vector Python SDK. It includes advanced options like sparse vectors, weighting strategies, and fusion algorithms, and demonstrates fetching initial results and subsequent batches. Requires an initialized 'index' object.

```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)

```

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

### Fetch Vector with Namespace (Python)

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

Illustrates fetching a vector while specifying a particular namespace. If no namespace is provided, the default namespace is used. This is helpful for organizing and querying vectors within different logical groups.

```python
index.fetch("id-4", namespace="ns")
```

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

### Resumable Query Response Structure

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

Example of a successful HTTP 200 response from a resumable query, including the query UUID and a list of scored vector results.

```json
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "scores": [
    {
      "id": "id-0",
      "score": 1.0,
      "metadata": {
        "link": "upstash.com"
      }
    },
    {
      "id": "id-1",
      "score": 0.99996454
    }
  ]
}
```

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

### GET /list-namespaces

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

Lists all active namespaces within the Upstash Vector database. This endpoint is useful for managing and organizing data across different logical groups.

```APIDOC
## GET /list-namespaces

### Description
Lists 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.

### Method
GET

### Endpoint
/list-namespaces

### Parameters
None

### Response
#### Success Response (200)
- **namespaces** (array) - A list of strings, where each string is a namespace name.

#### Response Example
```json
{
  "namespaces": ["default", "users", "products"]
}
```
```

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

### GET /v1/indexes/{index_name}/info

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

Retrieves comprehensive information about the specified Upstash Vector index, including vector counts, index size, and configuration details.

```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)
- **index_name** (string) - The name of the index.
- **vector_count** (integer) - The total number of vectors in the index.
- **dimension** (integer) - The dimension of the vectors.
- **similarity_function** (string) - The similarity function used by the index (e.g., COSINE, EUCLID, DOT).
- **created_at** (string) - The timestamp when the index was created.
- **namespaces** (array) - A list of namespaces within the index.

#### Response Example
```json
{
  "index_name": "my-vector-index",
  "vector_count": 10000,
  "dimension": 1536,
  "similarity_function": "COSINE",
  "created_at": "2023-10-27T10:00:00Z",
  "namespaces": ["default", "my-namespace"]
}
```
```

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

### POST /reset

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

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.

```APIDOC
## POST /reset

### Description
Resets all namespaces within an Upstash Vector index. This is a comprehensive data deletion operation that affects the entire index.

### Method
POST

### Endpoint
/reset

### Parameters

#### Request Body
- **all** (boolean) - Required - If true, resets all namespaces.

### Request Example
```json
{
  "all": true
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "All namespaces reset successfully."
}
```

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

### Execute Test Suite

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

Runs all defined tests for the project. Ensure that all required environment variables are set before execution.

```bash
bun run test
```

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

### Initialize Embeddings and Vector Store

Source: https://upstash.com/docs/vector/tutorials/huggingface-embeddings

Loads environment variables and initializes the Hugging Face embeddings model ('sentence-transformers/all-mpnet-base-v2') and the Upstash Vector store. The UpstashVectorStore automatically uses the loaded environment variables for configuration.

```python
# Load environment variables for API keys and Upstash configuration
from dotenv import load_dotenv
import os
load_dotenv()

# Import required libraries
from langchain_huggingface.embeddings import HuggingFaceEmbeddings
from langchain_community.vectorstores.upstash import UpstashVectorStore

# Initialize Hugging Face embeddings model
embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/all-mpnet-base-v2")

# Set up Upstash Vector Store (automatically uses the environment variables)
vector_store = UpstashVectorStore(embedding=embeddings)
```

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

### Parse Documents with LlamaParse

Source: https://upstash.com/docs/vector/integrations/llamaparse

Demonstrates how to use LlamaParse to parse a text document. It initializes the LlamaParse parser and uses SimpleDirectoryReader to load data from a specified file, extracting content as markdown.

```python
from llama_parse import LlamaParse
from llama_index.core import SimpleDirectoryReader

# Initialize the parser
parser = LlamaParse(result_type="markdown")

# Parse a document
file_extractor = {".txt": parser}
documents = SimpleDirectoryReader(
    input_files=["./documents/global_warming.txt"],
    file_extractor=file_extractor
).load_data()
```

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

### DELETE /delete

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

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.

```APIDOC
## DELETE /delete

### Description
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.

### Method
DELETE

### Endpoint
/delete

### Parameters

#### Request Body
- **prefix** (string) - Required - The prefix to match vector IDs against for deletion.

### Request Example
```json
{
  "prefix": "article_"
}
```

### Response
#### Success Response (200)
- **deleted** (integer) - The number of vectors deleted.

#### Response Example
```json
{
  "deleted": 3
}
```

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

### Fetch Vectors by IDs

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

Fetches vectors from the Upstash Vector index by providing an array of their IDs. Optionally includes metadata and targets the default namespace. This example uses cURL.

```APIDOC
## POST /fetch

### Description
Fetches vectors by providing an array of their IDs. Optionally includes metadata and targets the default namespace.

### Method
POST

### Endpoint
/fetch

### Parameters
#### Request Body
- **ids** (array of strings) - Required - An array of vector IDs to fetch.
- **includeMetadata** (boolean) - Optional - If true, includes metadata with the returned vectors.

### Request Example
```sh
curl $UPSTASH_VECTOR_REST_URL/fetch \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "ids": ["id-0"], "includeMetadata": true }'
```

### Response
#### Success Response (200)
- **vectors** (array of objects) - An array of vector objects, each containing 'id', 'vector', and optionally 'metadata'.

#### Response Example
```json
{
  "vectors": [
    {
      "id": "id-0",
      "vector": [0.1, 0.2, 0.3],
      "metadata": { "key": "value" }
    }
  ]
}
```
```

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

### Perform and Fetch Resumable Query (Python)

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

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. It requires the `upstash_vector` library.

```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
```

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

### Manage Namespaces and Queries with cURL

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

Demonstrates how to perform upsert operations, queries, and list namespaces within the Upstash Vector database using REST API calls.

```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"
```

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

### Insert Data into Upstash Vector Index

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

Demonstrates how to initialize an index client and perform an upsert operation to add vectors and metadata. This functionality is supported across Python, JavaScript, Go, PHP, and via raw curl requests.

```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"}}'
```

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

### Handle Synonyms with Semantic Cache

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

Demonstrates the semantic understanding capabilities of the cache by setting a value and retrieving it using a synonymous query string.

```typescript
await semanticCache.set("largest city in USA by population", "New York");
await delay(1000);

const result = await semanticCache.get("which is the most populated city in the USA?");
```

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

### Perform Batch Queries with Python SDK

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

Shows how to use the Upstash Vector Python SDK to execute multiple queries in a single call. This reduces latency by minimizing network round trips.

```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)
```

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

### Get Index Information (PHP)

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

Fetches detailed information about the Upstash Vector index using PHP. This requires the Upstash Vector REST URL and token for authentication and 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();
```

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

### Handle Complex Queries with Semantic Cache (TypeScript)

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

Illustrates how to handle complex queries using the Upstash Semantic Cache. It demonstrates setting a piece of information and then retrieving it using a rephrased query, showcasing the cache's ability to understand nuanced questions and provide relevant answers without re-computation. This is beneficial for improving query response times and reducing load on the primary data source.

```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?");
```

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

### Load and Prepare Document for Upstash Vector

Source: https://upstash.com/docs/vector/tutorials/langchain

This Python code demonstrates loading a text document using LangChain's TextLoader and splitting it into smaller chunks using CharacterTextSplitter, preparing it for insertion into the Upstash Vector index.

```python
from langchain_community.document_loaders import TextLoader
from langchain_text_splitters import CharacterTextSplitter

# Load the document
loader = TextLoader("documents/global_warming.txt")
documents = loader.load()
```

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

### Store Documents in Upstash Vector

Source: https://upstash.com/docs/vector/tutorials/gradio-application

Demonstrates how to create Document objects and upload them to the Upstash Vector store with specified batching parameters.

```python
documents = [
    Document(page_content="Global warming is causing sea levels to rise."),
    Document(page_content="AI is transforming many industries."),
    Document(page_content="Renewable energy is vital for sustainable development.")
]
vector_store.add_documents(documents=documents, batch_size=100, embedding_chunk_size=200)
```

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

### Query with DBSF Fusion

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

Demonstrates how to query the Upstash Vector database using the Distribution-Based Score Fusion (DBSF) algorithm for hybrid search via cURL.

```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"}'
```

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

### Configure Upstash Vector Store with Namespace

Source: https://upstash.com/docs/vector/integrations/llamaindex

Initialize the UpstashVectorStore instance with an optional namespace parameter to isolate data within the index.

```python
vector_store = UpstashVectorStore(
    url="your_upstash_url",
    token="your_upstash_token",
    namespace="your_namespace"
)
```

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

### Resume Resumable Query with cURL

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

Resumes a previously started query to fetch additional results using cURL. This is useful for paginating through search results. It requires the query UUID and the number of additional results to fetch.

```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 \
  }'
```

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

### Retrieve Index Statistics with Python

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

This snippet demonstrates how to initialize an Upstash Vector index from environment variables and call the info method to retrieve and print index statistics, including vector counts and namespace details.

```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)
```

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

### Rename Namespace using Curl

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

Provides an example of how to rename a namespace in Upstash Vector using a curl command. This requires specifying 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"
```

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

### List Namespaces - JavaScript

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

This JavaScript code snippet demonstrates how to import the Index class from the @upstash/vector package, initialize a new Index instance, and then call the listNamespaces() method.

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

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

await index.listNamespaces()
```

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

### Query Dense and Sparse Vectors in PHP

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

Demonstrates querying dense and sparse vectors separately using the PHP SDK, allowing for custom reranking logic on the client side.

```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,
));
```

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

### GET /index

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

Retrieves information about the Upstash Vector index, including vector counts, size, dimension, similarity function, and index type. It also provides details on dense and sparse index configurations, and namespace statistics.

```APIDOC
## GET /index

### Description
Retrieves information about the Upstash Vector index, including vector counts, size, dimension, similarity function, and index type. It also provides details on dense and sparse index configurations, and namespace statistics.

### Method
GET

### Endpoint
/index

### Parameters
None

### Request Example
None

### 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
      }
    }
  }
}
```
```

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

### Manage Sparse Vectors with Python

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

Shows how to upsert sparse vectors and perform queries using IDF weighting strategies. This is useful for keyword-based or hybrid search implementations.

```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")

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])),
    ]
)

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

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

### Retrieve Vectors in a Range (API Documentation)

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

Describes the GET /vectors/range API endpoint for retrieving vectors within a specified range. It supports filtering by prefix, pagination, and options to include vectors, metadata, and data in the response.

```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
```

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

### Query Document with LlamaIndex

Source: https://upstash.com/docs/vector/tutorials/llamaindex

This Python code demonstrates how to query the initialized LlamaIndex index. It creates a query engine and then uses it to ask questions about the loaded document, printing the responses.

```python
# Initialize the query engine
query_engine = index.as_query_engine()

# Query the document about global warming
res1 = query_engine.query("What is global warming?")
print(res1)

res2 = query_engine.query("How should we modify our diets to reduce our carbon footprint?")
print(res2)
```

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

### Initialize Upstash Vector Index

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

Initializes a connection to the Upstash Vector index using your REST URL and token. This is a client-side configuration step.

```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",
)
```
```

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

### Querying Vectors with Upstash Vector

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

Demonstrates how to perform a similarity search using a vector, including metadata and data in the response. It shows how to apply filters to narrow down results.

```python
import random
from upstash_vector import Index

index = Index.from_env()

# Generate a random vector for similarity comparison
dimension = 128
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)
```

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

### Initialize Upstash Vector Client

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

Methods to initialize the Upstash Vector client using environment variables or a configuration object.

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

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

const index = new Index();
```

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

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

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

### UpstashVectorStore Configuration

Source: https://upstash.com/docs/vector/tutorials/langchain

Methods for initializing the Upstash Vector store with namespaces and custom embedding providers.

```APIDOC
## UpstashVectorStore Initialization

### Description
Initializes the UpstashVectorStore instance for use within LangChain applications. Supports optional namespaces for data isolation and custom embedding models.

### Parameters
#### Constructor Arguments
- **embedding** (bool/object) - Required - Set to True for default or provide an embedding instance like OpenAIEmbeddings.
- **namespace** (string) - Optional - A string identifier to group and isolate documents within the index.

### Request Example
```python
# Using a namespace
store = UpstashVectorStore(embedding=True, namespace="my_namespace")

# Using OpenAI embeddings
from langchain_openai import OpenAIEmbeddings
store = UpstashVectorStore(embedding=OpenAIEmbeddings())
```

### Notes
- Use `similarity_search_with_score` to retrieve search results along with their similarity scores.
```

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

### Retrieve Index Statistics with TypeScript

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

Demonstrates how to call the info() method on an index instance to retrieve comprehensive metadata. The output includes total vector counts, pending processing counts, index size, and namespace details.

```typescript
const infoResponse = await index.info();
/*
{ 
  vectorCount: 17,
  pendingVectorCount: 0,
  indexSize: 551158,
  dimension: 1536,
  similarityFunction: "COSINE",
  namespaces: {
    "": { // default namespace
      vectorCount: 10,
      pendingVectorCount: 0,
    },
    "my-namespace": {
      vectorCount: 7,
      pendingVectorCount: 0,
    }
  }
}
*/
```

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

### Upsert Multiple Vectors

Source: https://upstash.com/docs/vector/sdks/php/commands/upsert-vectors

This code illustrates how to efficiently upsert multiple vectors into an Upstash Vector index using the `upsertMany()` method. It accepts an array of `VectorUpsert` objects. Examples are provided for both direct index operations and operations within a designated namespace.

```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->upsertMany([
  new VectorUpsert(
    id: '1',
    vector: createRandomVector(dimensions: 1536)
  ),
  new VectorUpsert(
    id: '2',
    vector: createRandomVector(dimensions: 1536)
  ),
]);
```

```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->namespace('my-namespace')->upsertMany([
  new VectorUpsert(
    id: '1',
    vector: createRandomVector(dimensions: 1536)
  ),
  new VectorUpsert(
    id: '2',
    vector: createRandomVector(dimensions: 1536)
  ),
]);
```

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

### Query Data with Upstash Vector PHP SDK

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

Shows how to perform a similarity query using the Upstash Vector PHP SDK. It initializes the index, executes a DataQuery, and prints the results.

```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());
}
```

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

### Upsert Vector with Metadata in Python

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

Demonstrates how to generate a random vector and upsert it with metadata into the Upstash Vector index using the Python SDK.

```python
import random
from upstash_vector import Index

index = Index.from_env()

def main():
    dimension = 128
    vector_to_upsert = [random.random() for _ in range(dimension)]
    metadata = {"text": "example test for metadata"}

    index.upsert(vectors=[
        ("id-for-vector", vector_to_upsert, metadata)
    ])
```

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

### Upsert Single Vector

Source: https://upstash.com/docs/vector/sdks/php/commands/upsert-vectors

This snippet demonstrates how to upsert a single vector into an Upstash Vector index. It utilizes the `upsert()` method with a `VectorUpsert` object containing the vector's ID and its vector data. The example shows both a basic upsert and an upsert within a specific namespace.

```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: '1',
  vector: createRandomVector(dimensions: 1536)
));
```

```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->namespace('my-namespace')->upsert(new VectorUpsert(
  id: '1',
  vector: createRandomVector(dimensions: 1536)
));
```

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

### Implement QA Logic and Gradio Interface

Source: https://upstash.com/docs/vector/tutorials/gradio-application

Sets up a Hugging Face QA pipeline and defines the Gradio interface function to perform similarity searches and answer user queries.

```python
qa_pipeline = pipeline("question-answering", model="distilbert-base-cased-distilled-squad")

def answer_question(query):
    results = vector_store.similarity_search(query, k=3)
    if results:
        context = results[0].page_content
        qa_input = {"question": query, "context": context}
        answer = qa_pipeline(qa_input)["answer"]
        return f"Answer: {answer}\n\nContext: {context}"
    else:
        return "No relevant context found."

iface = gr.Interface(
    fn=answer_question,
    inputs="text",
    outputs="text",
    title="RAG Application",
    description="Ask a question, and the app will retrieve relevant information and provide an answer."
)

iface.launch()
```

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

### Delete Vectors by ID Prefix

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

Deletes vectors from the index whose IDs start with a specified prefix. This is useful for batch deletion of vectors that share a common naming convention. Note that this operation might be less performant than deleting by specific IDs for very large datasets.

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

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

### Access Index Information Properties (PHP)

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

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. Requires the Upstash Vector PHP SDK.

```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');
```

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

### Set Request Timeout in Upstash Vector SDK (TypeScript)

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

Configures the Upstash Vector SDK to enforce a request timeout. This example sets a 1-second timeout using AbortSignal.timeout and includes error handling for TimeoutError. It's useful for preventing long-running requests from blocking operations.

```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);
  }
}
```

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

### Query Vectors with Metadata and Data in Python

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

Demonstrates a similarity search operation using the Python SDK. It allows filtering results and specifying whether to include metadata and data in the response.

```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)
```

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

### Access Namespace Information Properties (PHP)

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

Demonstrates how to access key properties of the NamespaceInfo object in PHP. Specifically, it shows how to retrieve the count of ready vectors and pending vectors (those currently being indexed) within a namespace. This is useful for monitoring the indexing status of your data.

```php
// To know the number of vectors ready to query.
$myNamespaceInfo->vectorCount;

// To know the number of vectors that are getting indexed.
$myNamespaceInfo->pendingVectorCount;
```

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

### Query Upstash Vector with Text in Go

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

Initializes a Go client to query an index using text data. It utilizes the upstash/vector-go package to perform the query.

```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,
	})
}
```

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

### Update Vector Metadata

Source: https://upstash.com/docs/vector/sdks/php/commands/upsert-vectors

This snippet shows how to update existing vector data in an Upstash Vector index using the `update()` method. It focuses on modifying the metadata associated with a vector ID. The example includes options for different metadata update modes and demonstrates usage within a specific namespace.

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorUpdate;
use Upstash\Vector\Enums\UpdateMode;

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

$index->update(new VectorUpdate(
  id: '1',
  metadata: ['foo' => 'baz'],
  metadataUpdateMode: UpdateMode::OVERWRITE,
));
```

```php
use Upstash\Vector\Index;
use Upstash\Vector\VectorUpdate;
use Upstash\Vector\Enums\UpdateMode;

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

$index->namespace('my-namespace')->update(new VectorUpdate(
  id: '1',
  metadata: ['foo' => 'baz'],
  metadataUpdateMode: UpdateMode::OVERWRITE,
));
```

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

### 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.

```APIDOC
## Namespace Operations (Python SDK)

### Description
Provides examples for managing namespaces, including upserting data, querying within a namespace, listing all namespaces, and deleting a specific namespace using the Upstash Vector Python SDK.

### Method
Various (SDK methods map to API calls)

### Endpoint
N/A (SDK abstraction)

### Parameters
See SDK documentation for specific method parameters.

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

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

### Request Example (List namespaces)
```python
namespaces = index.list_namespaces()
print(namespaces)
```

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

### Response
Responses vary based on the operation. Refer to SDK documentation for details on return values for upsert, query, list_namespaces, and delete_namespace.
```

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

### Query with Reciprocal Rank Fusion (RRF)

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

This snippet demonstrates how to perform a query using Reciprocal Rank Fusion (RRF) to combine dense and sparse vector search results. RRF focuses on the rank of results rather than their scores. The examples show how to configure the fusion algorithm in various programming languages and cURL.

```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,
)
```

```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,
});
```

```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,
	})
}
```

```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,
));
```

```shell
curl $UPSTASH_VECTOR_REST_URL/query \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{"vector": [0.5, 0.4], "sparseVector": {"indices": [3, 5], "values": [0.3, 0.5]}, "fusionAlgorithm": "RRF"}'
```

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

### Query Upstash Vector with Text

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

Illustrates how to initialize the Upstash Vector client and perform a text-based query. It requires valid REST credentials and returns the top K nearest neighbors.

```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,
  },
)
```

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

### Upsert and Query within a Namespace

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

This snippet demonstrates how to create a namespace implicitly, upsert a vector into it, and then query within that specific namespace. It requires the Upstash Vector URL and token for initialization. The operations are scoped to the specified namespace.

```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 Vectors with Metadata Filtering using JavaScript SDK

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

This JavaScript code snippet demonstrates how to query the Upstash Vector database for similar vectors using the JavaScript SDK. It includes examples of querying with metadata filtering and performing batch queries. The function supports including metadata, vectors, and raw data in the response.

```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 }
]);
```

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

### Hybrid Search and Fusion Queries with Python

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

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. The code shows both upserting a hybrid vector and querying with different fusion strategies.

```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
)
```

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

### Upsert Vector with Metadata using Upstash Vector SDK

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

This Python code snippet illustrates how to upsert a vector along with its associated metadata into the Upstash Vector database. It initializes the client using environment variables, generates a random vector, defines metadata, and then performs the upsert operation. This example assumes the vector dimension is 128.

```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)
    ])

main()
```

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

### List Namespaces - PHP

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

This PHP code snippet illustrates how to instantiate the Upstash Vector Index class using the provided URL and token, and subsequently invoke the listNamespaces() method.

```php
use Upstash\Vector\Index;

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

$index->listNamespaces();
```

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

### Execute Hybrid Resumable Query

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

Demonstrates advanced usage of resumable queries by incorporating sparse vectors, weighting strategies, and fusion algorithms for hybrid search scenarios.

```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)
```

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

### Perform Sparse Vector Operations with JavaScript SDK

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

Illustrates how to upsert sparse vectors and perform queries using IDF weighting or BM25 models for text data.

```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,
});

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

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

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
});
```

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

### Update with Namespace

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

Illustrates how to specify a namespace when performing an update operation. If no namespace is provided, the operation defaults to the base namespace.

```python
index.update(..., namespace="ns")
```

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

### Index and Query Parsed Content with Upstash Vector

Source: https://upstash.com/docs/vector/integrations/llamaparse

Shows how to index the documents parsed by LlamaParse into Upstash Vector and perform semantic queries. It loads environment variables, sets up the UpstashVectorStore, creates a StorageContext, builds a VectorStoreIndex, and then uses a query engine to ask questions about the document content.

```python
from llama_index.core import VectorStoreIndex
from llama_index.vector_stores.upstash import UpstashVectorStore
from llama_index.core import StorageContext
from dotenv import load_dotenv
import os

# Load environment variables
load_dotenv()

# Set up Upstash Vector Store
vector_store = UpstashVectorStore(
    url=os.getenv("UPSTASH_VECTOR_REST_URL"),
    token=os.getenv("UPSTASH_VECTOR_REST_TOKEN")
)

# Create storage context and index the parsed document
storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)

# Perform a query
query_engine = index.as_query_engine()
response = query_engine.query("What is the main topic discussed in the document?")
```

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

### Basic Semantic Retrieval with Upstash Semantic Cache (TypeScript)

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

Illustrates a basic semantic retrieval operation using the Upstash Semantic Cache. It demonstrates setting a key-value pair and then retrieving the value using a semantically similar query. A delay is included to ensure the index is updated before retrieval.

```typescript
await semanticCache.set("Capital of France", "Paris");
await delay(1000);

// 👇 outputs "Paris"
const result = await semanticCache.get("What's the capital of France?");
```

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

### Upserting with Namespaces

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

Demonstrates how to target a specific namespace during an upsert operation. If no namespace is specified, the default namespace is used.

```python
index.upsert(..., namespace="ns")
```

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

### Execute Namespace Query via API

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

Demonstrates querying a specific namespace using the Upstash Vector REST API via cURL.

```bash
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 }'
```

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

### Perform Resumable Queries with JavaScript

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

Initializes a resumable query session to fetch large result sets in batches. Provides methods to iterate through results and fetch subsequent pages.

```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,
});

for (let r of result) {
  console.log(r);
}
```

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

### Querying within a Namespace

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

Demonstrates how to scope a query operation to a specific namespace.

```python
index.query(..., namespace="ns")
```

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

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

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

Shows how to perform a hybrid search query using Reciprocal Rank Fusion (RRF). It combines dense and sparse vector information to improve search relevance.

```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,
	})
}
```

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

### Apply IDF Weighting Strategy to Queries

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

Demonstrates how to enable the IDF weighting strategy during vector queries. This helps improve search accuracy by accounting for document frequency in BM25 models.

```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"}'
```

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

### POST /fetch/{namespace}

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

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 /query

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

Queries the vector database using dense and sparse vectors with support for fusion algorithms like DBSF.

```APIDOC
## POST /query

### Description
Performs a hybrid search query using a dense vector, a sparse vector, and a specified fusion algorithm.

### Method
POST

### Endpoint
/query

### Parameters
#### Request Body
- **vector** (number[]) - Required - The dense query vector.
- **sparseVector** (object) - Required - The sparse query vector containing indices and values.
- **fusionAlgorithm** (string) - Optional - The algorithm to use for fusion (e.g., "DBSF").

### Request Example
```json
{"vector": [0.15, 0.25], "sparseVector": {"indices": [10], "values": [0.9]}, "fusionAlgorithm": "DBSF"}
```

### Response
#### Success Response (200)
- **matches** (array) - List of similar vectors found.
```

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

### POST /query/{namespace}

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

Queries vectors within a specific namespace.

```APIDOC
## POST /query/{namespace}

### Description
Performs a vector similarity search within the specified namespace.

### Method
POST

### Endpoint
/query/{namespace}

### Parameters
#### Path Parameters
- **namespace** (string) - Required - The name of the namespace to query.

#### Request Body
- **vector** (array) - Required - The query vector.
- **topK** (integer) - Required - Number of results to return.

### Request Example
{
  "vector": [0.9215, 0.3897],
  "topK": 5
}

### Response
#### Success Response (200)
- **results** (array) - List of matching vectors.
```

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

### Python Semantic Search with Upstash Vector

Source: https://upstash.com/docs/vector/tutorials/semantic_search

Demonstrates a complete semantic search workflow using Upstash Vector in Python. It loads credentials from a .env file, initializes the index, resets it, upserts sample documents (which are automatically embedded), and performs a search query. The results, including metadata, are then printed.

```python
from upstash_vector import Index
from dotenv import load_dotenv
import time

# Load environment variables from a .env file
load_dotenv()

# Initialize the index from environment variables (URL and token)
index = Index.from_env()

# Example documents to be indexed
documents = [
    {"id": "1", "text": "Python is a popular programming language."},
    {"id": "2", "text": "Machine learning enables computers to learn from data."},
    {"id": "3", "text": "Upstash provides low-latency database solutions."},
    {"id": "4", "text": "Semantic search is a technique for understanding the meaning of queries."},
    {"id": "5", "text": "Cloud computing allows for scalable and flexible resource management."}
]

# Reset the index to remove previous data
index.reset()

# Upsert documents into Upstash (embeddings are generated automatically)
for doc in documents:
    index.upsert(
        vectors=[
            (doc["id"], doc["text"], {"text": doc["text"]})
        ]
    )
    print(f"Document {doc['id']} inserted.")

# Wait for the documents to be indexed
time.sleep(1)

# Search for documents similar to the query
query = "What is Python?"
results = index.query(data=query, top_k=3, include_metadata=True)

# Display search results
print("Search Results:")
for result in results:
    print(f"ID: {result.id}")
    print(f"Score: {result.score:.4f}")
    print(f"Metadata: {result.metadata}")
    print("-" * 40)  # Separator line between results

```

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

### Executing Batch Queries with Upstash Vector

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

Shows how to execute multiple queries in a single network call using query_many to improve performance. Each query in the batch can have its own independent parameters.

```python
import random
from upstash_vector import Index

index = Index.from_env()

# Generate random vectors for batch comparison
dimension = 128
query_vectors = [[random.random() for _ in range(dimension)] for _ in range(2)]

# Execute the batch 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:")
    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)
```

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

### Perform Hybrid Query with Reciprocal Rank Fusion (Python)

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

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. This is useful for combining results from different search strategies.

```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,
)
```

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

### Query Vectors with Parameters (Python)

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

Demonstrates how to query the Upstash Vector index using a reference vector and various optional parameters. It allows for filtering, including metadata, data, and vectors in the response, and specifying the number of top results. This snippet requires the 'upstash_vector' package and environment variables for index configuration.

```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)
```

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

### List Namespaces - Python

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

This Python code snippet shows how to initialize the Upstash Vector Index and call the list_namespaces() method to retrieve all active namespaces.

```python
from upstash_vector import Index

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

index.list_namespaces()
```

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

### Query Index with Text Data (Python)

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

Demonstrates querying an Upstash Vector index by providing raw text data instead of a vector embedding, utilizing the Python SDK.

```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,
)
```

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

### Configure Retry Mechanism in Upstash Vector

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

Demonstrates how to initialize an Upstash Vector index with custom retry settings. This allows users to define the number of retry attempts and the time interval between them to handle transient network errors.

```python
from upstash_vector import Index

# Try 5 times with a 2-second interval between retries
index = Index.from_env(retries=5, retry_interval=2.0)
```

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

### Fetch Vectors by ID Prefix using cURL

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

Shows how to fetch vectors using a prefix for their IDs and from a specified namespace using a cURL command. This is useful for retrieving multiple vectors that share a common identifier prefix. The command includes authorization headers and a JSON payload with the IDs to fetch.

```sh
curl $UPSTASH_VECTOR_REST_URL/fetch/ns \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '{ "ids": ["id-0", "id-1"], "includeMetadata": true }'
```

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

### POST /query-data/ns

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

Queries for similar vectors within a specific namespace.

```APIDOC
## POST /query-data/ns

### Description
Queries for similar vectors within a specific namespace.

### Method
POST

### Endpoint
`/query-data/ns`

### Parameters
#### Request Body
- **data** (string) - Required - The textual data to use for querying.
- **topK** (number) - Required - The number of top similar vectors to return.

### Response
#### Success Response (200)
- **result** (Array<Object>) - An array of similar vectors found within the namespace.
```

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

### Execute Resumable Query via REST API

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

Performs a POST request to the resumable-query endpoint to initiate a paginated search session.

```bash
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 \
  }'
```

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

### Initialize Upstash Vector Store with LangChain

Source: https://upstash.com/docs/vector/tutorials/langchain

This Python code initializes the Upstash Vector store using environment variables for authentication. It configures the store to automatically generate embeddings via Upstash.

```python
from dotenv import load_dotenv
from langchain_community.vectorstores.upstash import UpstashVectorStore

load_dotenv()

# Create a vector store instance where embeddings are generated by Upstash
store = UpstashVectorStore(embedding=True)
```

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

### Initiate Resumable Query with Text Data

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

Demonstrates how to execute a query using raw text data, which is then embedded by the service. This endpoint allows for resuming queries and fetching additional results. It supports various parameters to customize the search, including metadata filtering, and controlling the inclusion of metadata, vectors, and data in the response.

```json
{
  "data": "Hello world",
  "topK": 2,
  "includeMetadata": true,
  "maxIdle": 3600
}
```

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

### Configure Namespaces in Upstash Semantic Cache

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

Demonstrates how to initialize the Upstash Semantic Cache with a specific namespace to partition and isolate data. This ensures that cached entries are scoped to the defined namespace.

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

const index = new Index();
const semanticCache = new SemanticCache({ index, minProximity: 0.95, namespace: "user1" });

await semanticCache.set("Capital of Turkey", "Ankara");
```

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

### Fetch Vectors by ID Prefix in PHP

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

Retrieves vectors matching a specific ID prefix, with options to include metadata, vectors, and raw 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->fetch(new VectorFetchByPrefix(
  prefix: 'users:',
  includeMetadata: true,
  includeVectors: true,
  includeData: true,
));

$results = $index->namespace('my-namespace')->fetch(new VectorFetchByPrefix(
  prefix: 'users:',
  includeMetadata: true,
  includeVectors: true,
  includeData: true,
));
```

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

### Fetch Vectors with Range and Pagination

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

Shows how to use the range method to retrieve vectors with pagination support. It includes metadata and a cursor for navigating through large datasets.

```typescript
const responseRange = await index.range(
    {
      cursor: 0,
      limit: 2,
      includeMetadata: true,
    },
    { namespace: "my-namespace" }
  );
```

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

### POST /reset/all

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

Resets all namespaces within the index, clearing all vectors and metadata from every namespace.

```APIDOC
## POST /reset/all

### Description
Clears all data from the index, including all namespaces.

### Method
POST

### Endpoint
/reset/all

### Response
#### Success Response (200)
- **message** (string) - Confirmation of the reset operation.
```

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

### POST /reset/all

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

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."
}
```
```

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

### Upsert Vectors with Data and Metadata

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

Demonstrates how to upsert vectors along with their associated data and metadata using Python, JavaScript, PHP, and curl. This allows storing contextual information directly with the vector, which can be retrieved during queries.

```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"
            }
        ]'
```

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

### Retrieve Namespace Information with Upstash Vector SDK

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

Shows how to fetch information for specific namespaces or the default namespace using the getNamespaceInfo() method. This is useful for monitoring the status of vectors within isolated segments of the index.

```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();

// Accessing namespace stats
$myNamespaceInfo->vectorCount;
$myNamespaceInfo->pendingVectorCount;
```

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

### Perform Range Queries with Upstash Vector Python SDK

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

Demonstrates how to execute range queries to scan vectors in an index. It includes options for filtering by namespace, including metadata or data, and handling pagination using cursors.

```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)
```

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

### Query Dense and Sparse Vectors with Custom Reranking

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

Illustrates querying dense and sparse vectors independently using the Upstash Vector Go SDK, enabling custom reranking of search results. This requires the 'github.com/upstash/vector-go' library and proper 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
}
```

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

### Upsert Sparse Vectors in Upstash Vector

Source: https://upstash.com/docs/vector/sdks/php/commands/upsert-vectors

Demonstrates how to upsert a sparse vector into an index. It shows both standard upsert operations and how to target a specific namespace.

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

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

$index->upsert(new VectorUpsert(
  id: '1',
  sparseVector: new SparseVector(
    indices: [0, 1],
    values: [1.0, 2.0],
  ),
));
```

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

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

$index->namespace('my-namespace')->upsert(new VectorUpsert(
  id: '1',
  sparseVector: new SparseVector(
    indices: [0, 1],
    values: [1.0, 2.0],
  ),
));
```

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

### Hybrid Search and Fusion Queries

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

Demonstrates how to upsert hybrid vectors and perform queries using RRF and DBSF fusion algorithms with the upstash-vector SDK.

```APIDOC
## Hybrid Search and Fusion Queries

### Description
This snippet demonstrates how to upsert hybrid vectors (dense + sparse) and perform queries using RRF and DBSF fusion algorithms via the Python SDK.

### Method
POST (via SDK)

### Endpoint
/upsert, /query

### Parameters
#### Request Body
- **vectors** (list) - Required - List of Vector objects containing id, vector, sparse_vector, and metadata.
- **fusion_algorithm** (string) - Optional - Algorithm to use: RRF or DBSF.

### Request Example
```python
index.upsert(vectors=[Vector(id="hybrid-1", vector=[0.1, 0.2], sparse_vector=SparseVector([10], [0.8]))])
```

### Response
#### Success Response (200)
- **status** (string) - Success confirmation.
```

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

### Filter Query Results by Metadata

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

Demonstrates how to apply metadata filters to query results to narrow down the search space.

```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*'",
)
```

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

### Configure Upstash Credentials

Source: https://upstash.com/docs/vector/tutorials/huggingface-embeddings

Creates a .env file to store Upstash Vector credentials (URL and Token). These environment variables are loaded using the python-dotenv library to configure the connection to Upstash Vector.

```dotenv
UPSTASH_VECTOR_REST_URL=your_upstash_url
UPSTASH_VECTOR_REST_TOKEN=your_upstash_token
```

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

### Embed and Store Documents in Upstash Vector

Source: https://upstash.com/docs/vector/tutorials/huggingface-embeddings

Creates sample documents and embeds them using the initialized Hugging Face embeddings. The documents are then added to the Upstash Vector store with specified batching parameters for efficient processing. The batch_size parameter controls HTTP request batching, while embedding_chunk_size controls parallel embedding.

```python
# Import the required Document class from LangChain
from langchain.schema import Document

# Sample documents to embed and store as Document objects
documents = [
    Document(page_content="Global warming is causing sea levels to rise."),
    Document(page_content="Artificial intelligence is transforming many industries."),
    Document(page_content="Renewable energy is vital for sustainable development.")
]

# Embed documents and store in Upstash Vector with batching
vector_store.add_documents(
    documents=documents,
    batch_size=100,               
    embedding_chunk_size=200      
)

print("Documents with embeddings have been stored in Upstash Vector.")
```

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

### POST /resumable-query/ns

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

Perform resumable queries within a specific namespace.

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

### Description
Perform queries that can be resumed to fetch additional results within a specified namespace. This is useful for organizing and querying data within different contexts.

### Method
POST

### Endpoint
/resumable-query/ns

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

#### Request Body
- **vector** (number[]) - Required - The query vector. The query vector should have the same dimensions as your index.
- **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. Defaults to 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. Defaults to 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. Defaults to false.
- **includeData** (boolean) - Optional - Whether to include the data of the vectors in the response, if any. Defaults to false.
- **filter** (string) - Optional - Metadata filter to apply.
- **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).

### Request Example
```sh 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
  }'
```

### Response
#### Success Response (200)
- **uuid** (string) - A unique identifier for the resumable query.
- **scores** (Object[]) - An array of scores for the returned vectors.
  - **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 200 OK
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "scores": [
    {
      "id": "id-0",
      "score": 1.0,
      "metadata": {
        "link": "upstash.com"
      }
    },
    {
      "id": "id-1",
      "score": 0.99996454
    }
  ]
}
```
```

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

### POST /resumable-query

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

Initiates a resumable query for finding similar vectors. This method returns an initial set of results and a handle to fetch subsequent batches. You can configure `max_idle` to set the maximum idle time in seconds before the query is automatically stopped.

```APIDOC
## POST /resumable-query

### Description
Initiates a resumable query for finding similar vectors. This method returns an initial set of results and a handle to fetch subsequent batches. You can configure `max_idle` to set the maximum idle time in seconds before the query is automatically stopped.

### Method
POST

### Endpoint
/resumable-query

### Parameters
#### Request Body
- **vector** (array of floats) - Required - The vector to search for similar vectors.
- **topK** (integer) - Required - The number of most similar vectors to return in the initial batch.
- **includeMetadata** (boolean) - Optional - If true, metadata associated with the vectors will be included in the response.
- **maxIdle** (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 similar vector objects.
- **handle** (string) - A unique identifier (handle) to be used for subsequent calls to fetch more results or stop the query.

#### Response Example
```json
{
  "result": [
    {
      "id": "vector-id-1",
      "score": 0.95,
      "vector": [0.1, 0.2],
      "metadata": { "key": "value" }
    }
  ],
  "handle": "550e8400-e29b-41d4-a716-446655440000"
}
```
```

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

### Upsert and Query with Custom OpenAI Embeddings

Source: https://upstash.com/docs/vector/integrations/ai-sdk

Demonstrates manual embedding generation using the Vercel AI SDK and OpenAI's text-embedding-ada-002 model. This method provides flexibility to use specific embedding models but requires managing vector dimensions.

```typescript
import { Index } from '@upstash/vector'
import { embed, embedMany } from 'ai'
import { openai } from '@ai-sdk/openai'

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

const embeddingModel = openai.embedding('text-embedding-ada-002')

async function generateEmbedding(value: string): Promise<number[]> {
  const input = value.replaceAll('\\n', ' ')
  const { embedding } = await embed({ model: embeddingModel, value: input })
  return embedding
}

export async function upsertEmbeddings(resourceId: string, content: string) {
  const chunks = content.trim().split('.').filter(i => i !== '')
  const { embeddings } = await embedMany({ model: embeddingModel, values: chunks })
  const toUpsert = embeddings.map((vector, i) => ({
    id: `${resourceId}-${i}`,
    vector: vector,
    metadata: { resourceId, content: chunks[i] },
  }))
  await index.upsert(toUpsert)
}

export async function findRelevantContent(query: string, k = 4) {
  const userEmbedding = await generateEmbedding(query)
  return await index.query({ vector: userEmbedding, topK: k, includeMetadata: true })
}
```

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

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

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

Illustrates how to perform hybrid queries using Reciprocal Rank Fusion (RRF) to combine dense and sparse vector search results.

```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,
});
```

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

### Querying Hybrid Index with Text Data

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

Demonstrates how to perform a hybrid search query by providing raw text. The service automatically handles embedding and returns the top-k results based on the index configuration.

```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,
)
```

```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,
  },
)
```

```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,
	})
}
```

```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,
));
```

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

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

### Fetch Vectors by IDs (Python)

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

Demonstrates how to fetch multiple vectors from an Upstash Vector index using a list of their IDs. It includes options to include the vector data, metadata, and associated data in the response. This is useful for retrieving specific, known vectors.

```python
from upstash_vector import Index

index = Index.from_env()

# Specify the identifiers of vectors to be fetched
ids_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)
```

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

### Handling Synonyms in Retrieval

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

Shows how the semantic cache can handle synonyms. By setting a key-value pair and then querying with a semantically related but different phrasing, the correct value is retrieved. A delay is included for index updates.

```typescript
await semanticCache.set("largest city in USA by population", "New York");
await delay(1000);

// Retrieve using a query with synonyms
const result = await semanticCache.get("which is the most populated city in the USA?");
// result will be "New York"
```

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

### 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. The results can then be combined and reranked using a custom algorithm or model.

```APIDOC
## Query Dense and Sparse Components

### Description
This endpoint allows querying the dense vector index and the sparse vector index separately. This is a prerequisite for applying custom reranking logic to the combined results.

### 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 nearest neighbors to return.

**For Sparse Query:**
- **sparseVector** (object) - Required - An object containing sparse vector data.
  - **indices** (array[integer]) - Required - The indices of the sparse vector.
  - **values** (array[float]) - Required - The values corresponding to the indices.
- **topK** (integer) - Optional - The number of nearest neighbors to return.

### Request Example
**Dense Query:**
```json
{
  "vector": [0.5, 0.4],
  "topK": 3
}
```

**Sparse Query:**
```json
{
  "sparseVector": {
    "indices": [3, 5],
    "values": [0.3, 0.5]
  },
  "topK": 3
}
```

### Response
#### Success Response (200)
- **vector** (array[object]) - A list of dense search results, each with an id, vector, and score.
- **sparseVector** (array[object]) - A list of sparse search results, each with an id, vector, and score.

#### Response Example
```json
{
  "vector": [
    {"id": "vec1", "vector": [0.5, 0.4], "score": 0.95},
    {"id": "vec2", "vector": [0.6, 0.3], "score": 0.90}
  ],
  "sparseVector": [
    {"id": "sp1", "vector": {"indices": [3, 5], "values": [0.3, 0.5]}, "score": 0.85},
    {"id": "sp2", "vector": {"indices": [1, 4], "values": [0.2, 0.7]}, "score": 0.80}
  ]
}
```
```

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

### Query Vector Index with IDF Weighting

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

Explains how to perform a query using the Inverse Document Frequency (IDF) weighting strategy. This is useful for BM25-style searches to prioritize rarer terms.

```json
{
  "data": "Upstash Vector",
  "topK": 5,
  "weightingStrategy": "IDF"
}
```

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

### Query Parsed Document with Upstash Vector and LLM

Source: https://upstash.com/docs/vector/tutorials/llamaparse

Indexes parsed documents into Upstash Vector and queries them using an LLM (OpenAI). This involves setting up the Upstash Vector store, creating a storage context, and initializing a query engine.

```python
from llama_index.core import VectorStoreIndex
from llama_index.vector_stores.upstash import UpstashVectorStore
from llama_index.core import StorageContext
import openai

# Load environment variables for API keys and Upstash configuration
from dotenv import load_dotenv
import os
load_dotenv()

# Set up OpenAI API key
openai.api_key = os.getenv("OPENAI_API_KEY")

# Set up Upstash Vector Store
upstash_vector_store = UpstashVectorStore(
    url=os.getenv("UPSTASH_VECTOR_REST_URL"),
    token=os.getenv("UPSTASH_VECTOR_REST_TOKEN"),
)

# Create a storage context for Upstash Vector and index the parsed document
storage_context = StorageContext.from_defaults(vector_store=upstash_vector_store)
index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)

# Create a query engine for the index and perform a query
query_engine = index.as_query_engine()
query = "What are the main points discussed in the document?"
response = query_engine.query(query)
print(response)
```

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

### Upsert and Query Text Data

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

Demonstrates how to upsert raw text data which is automatically embedded by the index and perform a similarity search using the Python SDK.

```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}")
```

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

### Query with Distribution-Based Score Fusion in Python

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

Perform a hybrid query using the Distribution-Based Score Fusion (DBSF) algorithm in Python. This requires initializing the Index and providing both dense and sparse vectors.

```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,
)
```

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

### POST /fetch

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

Fetches vectors from the index by providing a list of IDs or a prefix. Supports optional namespace scoping and configurable response fields.

```APIDOC
## POST /fetch

### Description
Fetches vectors from the default or specified namespace using provided IDs or an ID prefix.

### Method
POST

### Endpoint
/fetch/{namespace}

### Parameters
#### Path Parameters
- **namespace** (string) - Optional - The namespace to use. Defaults to the default namespace.

#### Request Body
- **ids** (string[]) - Optional - Array of vector ids to fetch.
- **prefix** (string) - Optional - Prefix of vector ids to fetch.
- **includeMetadata** (boolean) - Optional - Whether to include vector metadata. Default: false.
- **includeVectors** (boolean) - Optional - Whether to include vector values. Default: false.
- **includeData** (boolean) - Optional - Whether to include vector data. Default: false.

### Request Example
{
  "ids": ["id-0"],
  "includeMetadata": true
}

### Response
#### Success Response (200)
- **result** (Object[]) - Array of vectors in the same order as provided IDs.

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

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

### Query Data with Upstash Vector API

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

Demonstrates how to query data from the Upstash Vector index using the API. It shows how to set parameters like 'data', 'topK', and 'includeData' in the request body and explains the structure of the response, including optional vector data.

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

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

### POST /reset

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

Clears all vectors and metadata from a specific namespace or all namespaces within an index.

```APIDOC
## POST /reset

### Description
Clears all vectors and metadata from a particular namespace or all namespaces of an index.

### Method
POST

### Endpoint
/reset

### Parameters
#### Request Body
- **namespace** (string) - Optional - Specifies a namespace to reset. Leave empty for the default namespace.
- **all** (boolean) - Optional - Whether to reset all namespaces. Can only be set to true.

### Request Example
{
  "all": true
}

### Response
#### Success Response (200)
- **message** (string) - Returns 'Success' if the index is successfully reset.

#### Response Example
{
  "message": "Success"
}
```

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

### Query Vectors in Namespace via REST API

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

Shows how to perform a similarity search within a specific namespace using the POST /query endpoint. Requires a query vector and the topK parameter.

```json
{
  "vector": [0.9215, 0.3897],
  "topK": 5
}
```

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

### Create Resource Server Action

Source: https://upstash.com/docs/vector/integrations/ai-sdk

Defines a Next.js server action to validate input content using Zod and upsert it as embeddings into an Upstash Vector index. This serves as the data ingestion layer for the chatbot's knowledge base.

```typescript
'use server'

import { z } from 'zod'
import { upsertEmbeddings } from '@/lib/ai/upstashVector'

const NewResourceSchema = z.object({
  content: z.string().min(1),
})

export async function createResource(input: { content: string }) {
  const { content } = NewResourceSchema.parse(input)

  const resourceId = crypto.randomUUID()

  await upsertEmbeddings(resourceId, content)

  return `Resource ${resourceId} created and embedded.`
}
```

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

### List Namespaces

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

Lists the names of all namespaces within an Upstash Vector index. This is useful for discovering available data partitions.

```APIDOC
## GET /list-namespaces

### Description
Lists the names of the namespaces of an index.

### Method
GET

### Endpoint
/list-namespaces

### Parameters

#### Query Parameters
- **UPSTASH_VECTOR_REST_URL** (string) - Required - The base URL for the Upstash Vector REST API.
- **UPSTASH_VECTOR_REST_TOKEN** (string) - Required - The authorization token for accessing the Upstash Vector API.

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

### Response
#### Success Response (200)
- **namespaces** (string[]) - Required - Array of namespace names. Every index has at least one namespace called default namespace, whose name is the empty string `""`.

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

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

### Querying Vectors with Metadata

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

Shows how to query vectors and retrieve associated metadata. Metadata can be included in the query response for context.

```APIDOC
## POST /query

### Description
Queries the index for vectors similar to the provided vector, with options to include metadata.

### Method
POST

### Endpoint
/query

### Parameters
#### Query Parameters
- **include_metadata** (boolean) - Optional - If true, metadata associated with the vectors will be returned.
- **filter** (string) - Optional - A filter expression to narrow down the search results based on metadata.

#### Request Body
- **vector** (array[float]) - Required - The vector embedding to query with.
- **topK** (integer) - Required - The number of nearest neighbors to return.

### Request Example
```json
{
  "vector": [0.9215, 0.3897],
  "topK": 5,
  "includeMetadata": true
}
```

### Response
#### Success Response (200)
- **result** (array) - An array of matching vectors.
  - **id** (string) - The ID of the vector.
  - **score** (float) - The similarity score.
  - **metadata** (object) - The metadata associated with the vector (if requested).

#### Response Example
```json
{
  "result": [
    {
      "id": "id-0",
      "score": 1,
      "metadata": {
        "url": "https://imgur.com/z9AVZLb"
      }
    },
    {
      "id": "id-3",
      "score": 0.99961007,
      "metadata": {
        "url": "https://imgur.com/zfOPmnI"
      }
    }
  ]
}
```
```

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

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

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

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.

```APIDOC
## Query with Distribution-Based Score Fusion (PHP)

### Description
Performs a hybrid query using Distribution-Based Score Fusion (DBSF) in PHP. Initializes the Upstash Vector index and constructs a query object specifying the vector, sparse vector, and the DBSF fusion algorithm.

### Method
POST

### Endpoint
/query

### Parameters
#### Request Body
- **vector** (array) - Required - The dense vector for the query.
- **sparseVector** (object) - Required - An object containing `indices` (array of integers) and `values` (array of floats) for the sparse vector.
- **topK** (integer) - Required - The number of nearest neighbors to return.
- **includeMetadata** (boolean) - Optional - Whether to include metadata in the response.
- **fusionAlgorithm** (string) - Required - The fusion algorithm to use. Must be 'DISTRIBUTION_BASED_SCORE_FUSION'.

### Request Example
```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,
));
```

### Response
#### Success Response (200)
- **results** (array) - An array of similarity score objects, each containing vector ID, score, and metadata if requested.

#### Response Example
```json
[
  { "id": "vector1", "score": 0.95, "metadata": { "key": "value" } },
  { "id": "vector2", "score": 0.90, "metadata": { "key": "value" } }
]
```
```

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

### POST /resumable-query-next

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

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
```

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

### POST /query

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

Query an index using dense or sparse vectors to find similar items.

```APIDOC
## POST /query

### Description
Queries the index for vectors similar to the provided input. Supports dense vectors, sparse vectors, or raw text.

### Method
POST

### Endpoint
/query

### Request Body
- **topK** (number) - Required - Number of results to return.
- **sparseVector** (Object) - Optional - Sparse vector object with indices and values.
- **data** (string) - Optional - Text data to query.

### Response
#### Success Response (200)
- **result** (Array) - List of matched vectors with ID and score.

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

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

### Resetting Index or Namespace in PHP

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

Demonstrates how to reset the default namespace using the reset() method on the index object, or reset a specific named namespace by chaining the namespace() method.

```php
use Upstash\Vector\Index;

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

$index->reset();
```

```php
use Upstash\Vector\Index;

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

$index->namespace('my-namespace')->reset();
```

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

### POST /query/namespace-name

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

Queries vectors within a specified namespace. This endpoint allows for similarity searches within a particular data partition.

```APIDOC
## 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
}
```
```

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

### POST /resumable-query-next

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

Fetches the next batch of similar vectors using a handle from an initial resumable query. You can call this multiple times to iterate through the entire index. The `additional_k` parameter specifies how many more results to fetch.

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

### Description
Fetches the next batch of similar vectors using a handle from an initial resumable query. You can call this multiple times to iterate through the entire index. The `additional_k` parameter specifies how many more results to fetch.

### Method
POST

### Endpoint
/resumable-query-next

### Parameters
#### Request Body
- **uuid** (string) - Required - The unique identifier (handle) for the resumable query.
- **additionalK** (integer) - Optional - The number of additional similar vectors to fetch in this batch. Defaults to the value set during the initial query if not provided.

### Request Example
```json
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "additionalK": 3
}
```

### Response
#### Success Response (200)
- **results** (array) - An array of similar vector objects, each containing vector data and score.

#### Response Example
```json
[
  {
    "id": "vector-id-1",
    "score": 0.95,
    "vector": [0.1, 0.2],
    "metadata": { "key": "value" }
  },
  {
    "id": "vector-id-2",
    "score": 0.90,
    "vector": [0.3, 0.4],
    "metadata": { "key": "value" }
  }
]
```
```

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

### Query Hybrid Indexes (JavaScript)

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

Demonstrates querying dense and sparse data from a hybrid index using the Upstash Vector client, allowing for custom reranking logic.

```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 });
```

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

### POST /reset?namespace={namespace}

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

Resets all vectors and metadata from a specific namespace within an index. This operation is irreversible.

```APIDOC
## POST /reset?namespace={namespace}

### Description
Resets all vectors and metadata from a specific namespace within an index. This operation is irreversible.

### Method
POST

### Endpoint
/reset?namespace={namespace}

### Parameters
#### Query Parameters
- **namespace** (string) - Required - The name of the namespace to reset.

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

index.reset(namespace="ns")
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the reset operation was successful.

#### Response Example
```json
{
  "message": "Namespace 'ns' reset successfully"
}
```
```

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

### Upsert Sparse Vectors across SDKs and REST API

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

Demonstrates how to perform an upsert operation for sparse vectors using Python, JavaScript, Go, PHP, and cURL. Each implementation requires the Upstash Vector REST URL and Token for authentication.

```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", sparse_vector=SparseVector([1, 2], [0.1, 0.2])),
        Vector(id="id-1", 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',
  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",
			SparseVector: &vector.SparseVector{
				Indices: []int32{1, 2},
				Values:  []float32{0.1, 0.2},
			},
		},
		{
			Id: "id-1",
			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;

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

$index->upsertMany([
  new VectorUpsert(
    id: 'id-0',
    sparseVector: new SparseVector(
      indices: [1, 2],
      values: [0.1, 0.2],
    ),
  ),
  new VectorUpsert(
    id: 'id-1',
    sparseVector: new SparseVector(
      indices: [123, 44232],
      values: [0.5, 0.4],
    ),
  ),
]);
```

```shell
curl $UPSTASH_VECTOR_REST_URL/upsert \
  -H "Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN" \
  -d '[
    {"id": "id-0", "sparseVector": {"indices": [1, 2], "values": [0.1, 0.2]}},
    {"id": "id-1", "sparseVector": {"indices": [123, 44232], "values": [0.5, 0.4]}}
  ]'
```

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

### Hybrid Search and Fusion Queries (JavaScript)

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

Showcases how to upsert hybrid vectors and perform queries using different fusion algorithms (RRF, DBSF) with the @upstash/vector SDK.

```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,
});

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" }
  }
]);

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
});

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
});
```

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

### Upsert Vectors with Metadata

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

Demonstrates how to associate metadata with vectors during the upsert process. This allows for storing additional context alongside vector data.

```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"
   }
}'
```

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

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

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

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.

```APIDOC
## Implement Reciprocal Rank Fusion (RRF)

### Description
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.

### Method
POST

### Endpoint
/query

### Parameters
#### Request Body
- **vector** (array) - Required - The dense vector for the query.
- **sparse_vector** (object) - Optional - The sparse vector for the query.
  - **indices** (array) - Required - Indices of the sparse vector.
  - **values** (array) - Required - Values of the sparse vector.
- **fusion_algorithm** (string) - Optional - Specifies the fusion algorithm. Set to 'RRF' for Reciprocal Rank Fusion.

### Request Example
```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,
)
```

### Response
#### Success Response (200)
- **result** (array) - An array of search results, each containing id, score, and optional metadata.
  - **id** (string) - The ID of the matched vector.
  - **score** (number) - The similarity score.
  - **metadata** (object) - Optional metadata associated with the vector.

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

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

### Resetting All Namespaces in PHP

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

Shows how to clear data across all namespaces within an Upstash Vector index using the resetAll() method.

```php
use Upstash\Vector\Index;

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

$index->resetAll();
```

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

### Implement Chat API Route

Source: https://upstash.com/docs/vector/integrations/ai-sdk

Sets up a POST route handler using the Vercel AI SDK to stream responses from an OpenAI model. It integrates custom tools for adding resources and retrieving relevant content from the Upstash Vector index.

```typescript
import { openai } from '@ai-sdk/openai'
import { streamText, tool } from 'ai'
import { z } from 'zod'
import { createResource } from '@/lib/actions/resources'
import { findRelevantContent } from '@/lib/ai/upstashVector'

export const maxDuration = 30

export async function POST(req: Request) {
  const { messages } = await req.json()

  const result = streamText({
    model: openai('gpt-4o'),
    messages,
    system: `You are a helpful RAG assistant. You have the ability to add and retrieve content from your knowledge base.`,
    tools: {
      addResource: tool({
        description: `Add new content to the knowledge base.`,
        parameters: z.object({
          content: z.string().describe('The content to embed and store'),
        }),
        execute: async ({ content }) => {
          const msg = await createResource({ content })
          return msg
        },
      }),
      getInformation: tool({
        description: `Retrieve relevant knowledge from your knowledge base to answer user queries.`,
        parameters: z.object({
          question: z.string().describe('The question to search for'),
        }),
        execute: async ({ question }) => {
          const hits = await findRelevantContent(question)
          return hits
        },
      }),
    },
  })

  return result.toDataStreamResponse()
}
```

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

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

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

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.

```APIDOC
## Upstash Semantic Cache Operations

### Description
This example demonstrates how to use the Upstash Semantic Cache to store and retrieve information using natural language queries. It shows setting a value with a specific question and then retrieving it using a rephrased question, highlighting the cache's semantic understanding capabilities.

### Method
POST (for set), GET (for get - conceptual, SDK handles actual HTTP)

### Endpoint
/set (conceptual for set), /get (conceptual for get)

### Parameters
#### Set Operation
- **key** (string) - The natural language question or statement to store.
- **value** (string) - The answer or information to associate with the key.

#### Get Operation
- **key** (string) - The natural language question to retrieve information for.

### Request Example
```typescript
// Assuming 'semanticCache' is an initialized instance of the Upstash Semantic Cache client
// and 'delay' is a utility function for pausing execution.

await semanticCache.set("year in which the Berlin wall fell", "1989");
await delay(1000);

// The cache should return "1989" even though the question is rephrased.
const result = await semanticCache.get("what's the year the Berlin wall destroyed?"); 
console.log(result); // Output: "1989"
```

### Response
#### Success Response (200)
- **get**: Returns the cached value associated with the semantic key.
- **set**: Typically returns a success confirmation.

#### Response Example
```json
// For get operation:
"1989"

// For set operation (example):
{
  "success": true
}
```
```

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

### Upsert Vectors with JavaScript SDK

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

Demonstrates how to add single or multiple vectors to an Upstash Vector index. Requires environment variables for authentication and 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" } }
]);
```

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

### 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.

```APIDOC
## Upsert and Query Raw Text using Python

### Description
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.

### Method
POST (for upsert), GET (for query)

### Endpoint
/upsert, /query

### Parameters
#### Request Body (upsert)
- **vectors** (array) - Required - An array of tuples, where each tuple contains a vector ID, the text data, and optional metadata.

#### Query Parameters (query)
- **data** (string) - Required - The text to query.
- **top_k** (integer) - Optional - The number of nearest neighbors to return.
- **include_data** (boolean) - Optional - Whether to include the vector data in the response.
- **include_metadata** (boolean) - Optional - Whether to include the vector metadata in the response.

### Request Example (upsert)
```python
index.upsert(
    vectors=[
        ("text-1", "Upstash is a serverless data platform.", {"source": "homepage"}),
        ("text-2", "Vector databases enable semantic search.", {"source": "docs"}),
    ]
)
```

### Request Example (query)
```python
results = index.query(
    data="What is Upstash?",
    top_k=3,
    include_data=True,
    include_metadata=True
)
```

### Response (query)
#### Success Response (200)
- **results** (array) - An array of similarity score objects, each containing vector ID, score, data, and metadata if requested.

#### Response Example (query)
```
[ 
  {'id': 'text-1', 'score': 0.8, 'data': 'Upstash is a serverless data platform.', 'metadata': {'source': 'homepage'}}
]
```
```