@mastra/mcp-docs-server 1.0.0-beta.5 → 1.0.0-beta.7

package/.docs/raw/observability/tracing/exporters/arize.mdx

@@ -182,10 +182,46 @@ new ArizeExporter({
 });
 ```
 
+### Custom metadata
+
+Non-reserved span attributes are serialized into the OpenInference `metadata` payload and surface in Arize/Phoenix. You can add them via `tracingOptions.metadata`:
+
+```ts
+await agent.generate(input, {
+  tracingOptions: {
+    metadata: {
+      companyId: "acme-co",
+      tier: "enterprise",
+    },
+  },
+});
+```
+
+Reserved fields such as `input`, `output`, `sessionId`, thread/user IDs, and OpenInference IDs are excluded automatically.
+
 ## OpenInference Semantic Conventions
 
 This exporter implements the [OpenInference Semantic Conventions](https://github.com/Arize-ai/openinference/tree/main/spec) for generative AI applications, providing standardized trace structure across different observability platforms.
 
+## Using Tags
+
+Tags help you categorize and filter traces in Phoenix and Arize AX. Add tags when executing agents or workflows:
+
+```typescript
+const result = await agent.generate({
+  messages: [{ role: "user", content: "Hello" }],
+  tracingOptions: {
+    tags: ["production", "experiment-v2", "user-request"],
+  },
+});
+```
+
+Tags appear as the `tag.tags` attribute following OpenInference conventions and can be used to filter and search traces. Common use cases include:
+
+- Environment labels: `"production"`, `"staging"`
+- Experiment tracking: `"experiment-v1"`, `"control-group"`
+- Priority levels: `"priority-high"`, `"batch-job"`
+
 ## Related
 
 - [Tracing Overview](/docs/v1/observability/tracing/overview)

package/.docs/raw/observability/tracing/exporters/braintrust.mdx

@@ -65,6 +65,25 @@ new BraintrustExporter({
 });
 ```
 
+## Using Tags
+
+Tags help you categorize and filter traces in the Braintrust dashboard. Add tags when executing agents or workflows:
+
+```typescript
+const result = await agent.generate({
+  messages: [{ role: "user", content: "Hello" }],
+  tracingOptions: {
+    tags: ["production", "experiment-v2", "user-request"],
+  },
+});
+```
+
+Tags appear in Braintrust's trace view and can be used to filter and search traces. Common use cases include:
+
+- Environment labels: `"production"`, `"staging"`
+- Experiment tracking: `"experiment-v1"`, `"control-group"`
+- Priority levels: `"priority-high"`, `"batch-job"`
+
 ## Related
 
 - [Tracing Overview](/docs/v1/observability/tracing/overview)

package/.docs/raw/observability/tracing/exporters/langfuse.mdx

@@ -107,7 +107,90 @@ new LangfuseExporter({
 });
 ```
 
+## Prompt Linking
+
+You can link LLM generations to prompts stored in [Langfuse Prompt Management](https://langfuse.com/docs/prompt-management). This enables version tracking and metrics for your prompts.
+
+### Using the Helper (Recommended)
+
+Use `withLangfusePrompt` with `buildTracingOptions` for the cleanest API:
+
+```typescript title="src/agents/support-agent.ts"
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+import { buildTracingOptions } from "@mastra/observability";
+import { withLangfusePrompt } from "@mastra/langfuse";
+import { Langfuse } from "langfuse";
+
+const langfuse = new Langfuse({
+  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
+  secretKey: process.env.LANGFUSE_SECRET_KEY!,
+});
+
+// Fetch the prompt from Langfuse Prompt Management
+const prompt = await langfuse.getPrompt("customer-support");
+
+export const supportAgent = new Agent({
+  name: "support-agent",
+  instructions: prompt.prompt, // Use the prompt text from Langfuse
+  model: openai("gpt-4o"),
+  defaultGenerateOptions: {
+    tracingOptions: buildTracingOptions(withLangfusePrompt(prompt)),
+## Using Tags
+
+Tags help you categorize and filter traces in the Langfuse dashboard. Add tags when executing agents or workflows:
+
+```typescript
+const result = await agent.generate({
+  messages: [{ role: "user", content: "Hello" }],
+  tracingOptions: {
+    tags: ["production", "experiment-v2", "user-request"],
+  },
+});
+```
+
+The `withLangfusePrompt` helper automatically extracts `name`, `version`, and `id` from the Langfuse prompt object.
+
+### Manual Fields
+
+You can also pass manual fields if you're not using the Langfuse SDK:
+
+```typescript
+const tracingOptions = buildTracingOptions(
+  withLangfusePrompt({ name: "my-prompt", version: 1 }),
+);
+
+// Or with just an ID
+const tracingOptions = buildTracingOptions(
+  withLangfusePrompt({ id: "prompt-uuid-12345" }),
+);
+```
+
+### Prompt Object Fields
+
+The prompt object supports these fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | The prompt name in Langfuse |
+| `version` | number | The prompt version number |
+| `id` | string | The prompt UUID for direct linking |
+
+You can link prompts using either:
+- `id` alone (the UUID uniquely identifies a prompt version)
+- `name` + `version` together
+- All three fields
+
+When set on a `MODEL_GENERATION` span, the Langfuse exporter automatically links the generation to the corresponding prompt.
+Tags appear in Langfuse's trace view and can be used to filter and search traces. Common use cases include:
+
+- Environment labels: `"production"`, `"staging"`
+- Experiment tracking: `"experiment-v1"`, `"control-group"`
+- Priority levels: `"priority-high"`, `"batch-job"`
+- User segments: `"beta-user"`, `"enterprise"`
+
 ## Related
 
 - [Tracing Overview](/docs/v1/observability/tracing/overview)
 - [Langfuse Documentation](https://langfuse.com/docs)
+- [Langfuse Prompt Management](https://langfuse.com/docs/prompt-management)

package/.docs/raw/observability/tracing/exporters/langsmith.mdx

@@ -23,6 +23,7 @@ npm install @mastra/langsmith@beta
 
 ```bash title=".env"
 LANGSMITH_API_KEY=ls-xxxxxxxxxxxx
+LANGCHAIN_PROJECT=my-project  # Optional: default project for traces
 LANGSMITH_BASE_URL=https://api.smith.langchain.com  # Optional for self-hosted
 ```
 
@@ -60,6 +61,7 @@ new LangSmithExporter({
 
   // Optional settings
   apiUrl: process.env.LANGSMITH_BASE_URL, // Default: https://api.smith.langchain.com
+  projectName: "my-project", // Project to send traces to (overrides LANGCHAIN_PROJECT env var)
   callerOptions: {
     // HTTP client options
     timeout: 30000, // Request timeout in ms
@@ -73,6 +75,16 @@ new LangSmithExporter({
 });
 ```
 
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `LANGSMITH_API_KEY` | Your LangSmith API key (required) |
+| `LANGCHAIN_PROJECT` | Default project name for traces (optional, defaults to "default") |
+| `LANGSMITH_BASE_URL` | API URL for self-hosted instances (optional) |
+
+The `projectName` config option takes precedence over the `LANGCHAIN_PROJECT` environment variable, allowing you to programmatically route traces to different projects.
+
 ## Related
 
 - [Tracing Overview](/docs/v1/observability/tracing/overview)

package/.docs/raw/observability/tracing/exporters/otel.mdx

@@ -5,13 +5,13 @@ description: "Send traces to any OpenTelemetry-compatible observability platform
 
 # OpenTelemetry Exporter
 
-:::warning
+The OpenTelemetry (OTEL) exporter sends your traces to any OTEL-compatible observability platform using standardized [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). This ensures broad compatibility with platforms like Datadog, New Relic, SigNoz, MLflow, Dash0, Traceloop, Laminar, and more.
 
-The OpenTelemetry exporter is currently **experimental**. APIs and configuration options may change in future releases.
+:::info Looking for bidirectional OTEL integration?
 
-:::
+If you have existing OpenTelemetry instrumentation and want Mastra traces to inherit context from active OTEL spans, see the [OpenTelemetry Bridge](/docs/v1/observability/tracing/bridges/otel) instead.
 
-The OpenTelemetry (OTEL) exporter sends your traces to any OTEL-compatible observability platform using standardized [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). This ensures broad compatibility with platforms like Datadog, New Relic, SigNoz, MLflow, Dash0, Traceloop, Laminar, and more.
+:::
 
 ## Installation
 
@@ -198,33 +198,26 @@ new OtelExporter({
 
 ## OpenTelemetry Semantic Conventions
 
-The exporter follows [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/), ensuring compatibility with observability platforms:
+The exporter follows [OpenTelemetry Semantic Conventions for GenAI v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai), ensuring compatibility with observability platforms:
 
 ### Span Naming
 
-- **LLM Operations**: `chat {model}` or `tool_selection {model}`
-- **Tool Execution**: `tool.execute {tool_name}`
-- **Agent Runs**: `agent.{agent_id}`
-- **Workflow Runs**: `workflow.{workflow_id}`
+- **LLM Operations**: `chat {model}`
+- **Tool Execution**: `execute_tool {tool_name}`
+- **Agent Runs**: `invoke_agent {agent_id}`
+- **Workflow Runs**: `invoke_workflow {workflow_id}`
 
 ### Key Attributes
 
 - `gen_ai.operation.name` - Operation type (chat, tool.execute, etc.)
-- `gen_ai.system` - AI provider (openai, anthropic, etc.)
+- `gen_ai.provider.name` - AI provider (openai, anthropic, etc.)
 - `gen_ai.request.model` - Model identifier
+- `gen_ai.input.messages` - Chat history provided to the model
+- `gen_ai.output.messages` - Messages returned by the model
 - `gen_ai.usage.input_tokens` - Number of input tokens
 - `gen_ai.usage.output_tokens` - Number of output tokens
 - `gen_ai.request.temperature` - Sampling temperature
-- `gen_ai.response.finish_reasons` - Completion reason
-
-## Buffering Strategy
-
-The exporter buffers spans until a trace is complete:
-
-1. Collects all spans for a trace
-2. Waits 5 seconds after root span completes
-3. Exports complete trace with preserved parent-child relationships
-4. Ensures no orphaned spans
+- `gen_ai.response.finish_reasons` - Completion reasons
 
 ## Protocol Selection Guide
 
@@ -264,10 +257,29 @@ Install the suggested package for your provider.
 1. **Wrong protocol package**: Verify you installed the correct exporter for your provider
 2. **Invalid endpoint**: Check endpoint format matches provider requirements
 3. **Authentication failures**: Verify API keys and headers are correct
-4. **No traces appearing**: Check that traces complete (root span must end)
+
+## Using Tags
+
+Tags help you categorize and filter traces in your observability platform. Add tags when executing agents or workflows:
+
+```typescript
+const result = await agent.generate({
+  messages: [{ role: "user", content: "Hello" }],
+  tracingOptions: {
+    tags: ["production", "experiment-v2", "user-request"],
+  },
+});
+```
+
+Tags are exported as a JSON string in the `mastra.tags` span attribute for broad backend compatibility. Common use cases include:
+
+- Environment labels: `"production"`, `"staging"`
+- Experiment tracking: `"experiment-v1"`, `"control-group"`
+- Priority levels: `"priority-high"`, `"batch-job"`
 
 ## Related
 
 - [Tracing Overview](/docs/v1/observability/tracing/overview)
-- [OpenTelemetry GenAI Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
+- [OpenTelemetry Bridge](/docs/v1/observability/tracing/bridges/otel)
+- [OpenTelemetry Semantic Conventions for GenAI v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai)
 - [OTEL Exporter Reference](/reference/v1/observability/tracing/exporters/otel)

package/.docs/raw/observability/tracing/exporters/posthog.mdx

@@ -101,6 +101,26 @@ new PosthogExporter({
 });
 ```
 
+## Using Tags
+
+Tags help you categorize and filter traces in PostHog's AI analytics. Add tags when executing agents or workflows:
+
+```typescript
+const result = await agent.generate({
+  messages: [{ role: "user", content: "Hello" }],
+  tracingOptions: {
+    tags: ["production", "experiment-v2", "user-request"],
+  },
+});
+```
+
+Tags are added as event properties where the tag name is the key and the value is set to `true`. In PostHog's trace view, filter by a tag using the `is set` filter (e.g., "production is set" shows all traces with the production tag). Common use cases include:
+
+- Environment labels: `"production"`, `"staging"`
+- Experiment tracking: `"experiment-v1"`, `"control-group"`
+- Priority levels: `"priority-high"`, `"batch-job"`
+- User segments: `"beta-user"`, `"enterprise"`
+
 ## Related
 
 - [Tracing Overview](/docs/v1/observability/tracing/overview)

package/.docs/raw/observability/tracing/overview.mdx

@@ -99,6 +99,23 @@ In addition to the internal exporters, Mastra supports integration with popular
 - **[OpenTelemetry](/docs/v1/observability/tracing/exporters/otel)** - Deliver traces to any OpenTelemetry-compatible observability system
   - Supports: Dash0, MLflow, Laminar, New Relic, SigNoz, Traceloop, Zipkin, and others!
 
+## Bridges
+
+Bridges provide bidirectional integration with external tracing systems. Unlike exporters that send trace data to external platforms, bridges create native spans in external systems and inherit context from them. This enables Mastra operations to participate in existing distributed traces.
+
+- **[OpenTelemetry Bridge](/docs/v1/observability/tracing/bridges/otel)** - Integrate with existing OpenTelemetry infrastructure
+
+### Bridges vs Exporters
+
+| Feature | Bridges | Exporters |
+| --- | --- | --- |
+| Creates native spans in external systems | Yes | No |
+| Inherits context from external systems | Yes | No |
+| Sends data to backends | Via external SDK | Directly |
+| Use case | Existing distributed tracing | Standalone Mastra tracing |
+
+You can use both together — a bridge for context propagation and exporters to send traces to additional destinations.
+
 ## Sampling Strategies
 
 Sampling allows you to control which traces are collected, helping you balance between observability needs and resource costs. In production environments with high traffic, collecting every trace can be expensive and unnecessary. Sampling strategies let you capture a representative subset of traces while ensuring you don't miss critical information about errors or important operations.
@@ -200,7 +217,6 @@ Use `configSelector` to choose the appropriate tracing configuration based on re
 ```ts title="src/mastra/index.ts" showLineNumbers copy
 export const mastra = new Mastra({
   observability: new Observability({
-    default: { enabled: true }, // Provides 'default' instance
     configs: {
       langfuse: {
         serviceName: "langfuse-service",
@@ -233,7 +249,7 @@ export const mastra = new Mastra({
         return "langfuse";
       }
 
-      return "default";
+      throw new Error('no config found')
     },
   }),
 });
@@ -448,6 +464,60 @@ requestContext.set("session", { data: { experimentId: "exp-999" } });
 3. **Child Span Extraction**: Child spans can also extract metadata if you pass `requestContext` when creating them
 4. **Metadata Precedence**: Explicit metadata passed to span options always takes precedence over extracted metadata
 
+### Adding Tags to Traces
+
+Tags are string labels that help you categorize and filter traces. Unlike metadata (which contains structured key-value data), tags are simple strings designed for quick filtering and organization.
+
+Use `tracingOptions.tags` to add tags when executing agents or workflows:
+
+```ts showLineNumbers copy
+// With agents
+const result = await agent.generate({
+  messages: [{ role: "user", content: "Hello" }],
+  tracingOptions: {
+    tags: ["production", "experiment-v2", "user-request"],
+  },
+});
+
+// With workflows
+const run = await mastra.getWorkflow("myWorkflow").createRun();
+const result = await run.start({
+  inputData: { data: "process this" },
+  tracingOptions: {
+    tags: ["batch-processing", "priority-high"],
+  },
+});
+```
+
+#### How Tags Work
+
+- **Root span only**: Tags are applied only to the root span of a trace (the agent run or workflow run span)
+- **Widely supported**: Tags are supported by most exporters for filtering and searching traces:
+  - **Braintrust** - Native `tags` field
+  - **Langfuse** - Native `tags` field on traces
+  - **ArizeExporter** - `tag.tags` OpenInference attribute
+  - **OtelExporter** - `mastra.tags` span attribute
+  - **OtelBridge** - `mastra.tags` span attribute
+- **Combinable with metadata**: You can use both `tags` and `metadata` in the same `tracingOptions`
+
+```ts showLineNumbers copy
+const result = await agent.generate({
+  messages: [{ role: "user", content: "Analyze this" }],
+  tracingOptions: {
+    tags: ["production", "analytics"],
+    metadata: { userId: "user-123", experimentId: "exp-456" },
+  },
+});
+```
+
+#### Common Tag Patterns
+
+- **Environment**: `"production"`, `"staging"`, `"development"`
+- **Feature flags**: `"feature-x-enabled"`, `"beta-user"`
+- **Request types**: `"user-request"`, `"batch-job"`, `"scheduled-task"`
+- **Priority levels**: `"priority-high"`, `"priority-low"`
+- **Experiments**: `"experiment-v1"`, `"control-group"`, `"treatment-a"`
+
 #### Child Spans and Metadata Extraction
 
 When creating child spans within tools or workflow steps, you can pass the `requestContext` parameter to enable metadata extraction:
@@ -751,10 +821,6 @@ Mastra automatically creates spans for:
 
 ## See Also
 
-### Examples
-
-- [Basic Tracing Example](/examples/v1/observability/basic-ai-tracing) - Working implementation
-
 ### Reference Documentation
 
 - [Configuration API](/reference/v1/observability/tracing/configuration) - ObservabilityConfig details
@@ -773,6 +839,10 @@ Mastra automatically creates spans for:
 - [MLflow](/reference/v1/observability/tracing/exporters/otel#mlflow) - MLflow OTLP endpoint setup
 - [OpenTelemetry](/reference/v1/observability/tracing/exporters/otel) - OTEL-compatible platforms
 
+### Bridges
+
+- [OpenTelemetry Bridge](/reference/v1/observability/tracing/bridges/otel) - OTEL context integration
+
 ### Processors
 
 - [Sensitive Data Filter](/docs/v1/observability/tracing/processors/sensitive-data-filter) - Data redaction

package/.docs/raw/observability/tracing/processors/sensitive-data-filter.mdx

@@ -293,4 +293,3 @@ This ensures that processing errors don't prevent traces from being exported or
 ## Related
 
 - [SensitiveDataFilter API](/reference/v1/observability/tracing/processors/sensitive-data-filter)
-- [Basic Tracing Example](/examples/v1/observability/basic-ai-tracing)

package/.docs/raw/rag/retrieval.mdx

@@ -52,6 +52,8 @@ const results = await pgVector.query({
 console.log(results);
 ```
 
+The `topK` parameter specifies the maximum number of most similar results to return from the vector search.
+
 Results include both the text content and a similarity score:
 
 ```ts showLineNumbers copy
@@ -70,8 +72,6 @@ Results include both the text content and a similarity score:
 ];
 ```
 
-For an example of how to use the basic retrieval method, see the [Retrieve Results](/examples/v1/rag/query/retrieve-results) example.
-
 ## Advanced Retrieval options
 
 ### Metadata Filtering
@@ -170,7 +170,14 @@ This is particularly useful when:
 
 #### Database-Specific Configurations
 
-The Vector Query Tool supports database-specific configurations that enable you to leverage unique features and optimizations of different vector stores:
+The Vector Query Tool supports database-specific configurations that enable you to leverage unique features and optimizations of different vector stores.
+
+:::note
+These configurations are for **query-time options** like namespaces, performance tuning, and filtering—not for database connection setup. 
+
+
+Connection credentials (URLs, auth tokens) are configured when you instantiate the vector store class (e.g., `new LibSQLVector({ connectionUrl: '...' })`).
+:::
 
 ```ts showLineNumbers copy
 // Pinecone with namespace
@@ -510,13 +517,25 @@ const relevanceProvider = new MastraAgentRelevanceScorer('relevance-scorer', "op
 const rerankedResults = await rerank({
   results: initialResults,
   query,
-  provider: relevanceProvider,
+  scorer: relevanceProvider,
   options: {
+    weights: {
+      semantic: 0.5, // How well the content matches the query semantically
+      vector: 0.3, // Original vector similarity score
+      position: 0.2, // Preserves original result ordering
+    },
     topK: 10,
   },
 );
 ```
 
+The weights control how different factors influence the final ranking:
+
+- `semantic`: Higher values prioritize semantic understanding and relevance to the query
+- `vector`: Higher values favor the original vector similarity scores
+- `position`: Higher values help maintain the original ordering of results
+
+
 > **Note:** For semantic scoring to work properly during re-ranking, each result must include the text content in its `metadata.text` field.
 
 You can also use other relevance score providers like Cohere or ZeroEntropy:
@@ -533,8 +552,6 @@ The re-ranked results combine vector similarity with semantic understanding to i
 
 For more details about re-ranking, see the [rerank()](/reference/v1/rag/rerankWithScorer) method.
 
-For an example of how to use the re-ranking method, see the Re-ranking Results example in the examples section.
-
 ### Graph-based Retrieval
 
 For documents with complex relationships, graph-based retrieval can follow connections between chunks. This helps when:

package/.docs/raw/rag/vector-databases.mdx

@@ -252,6 +252,27 @@ await store.createIndex({
   dimension: 1536,
 });
 
+await store.upsert({
+  indexName: "my-collection",
+  vectors: embeddings,
+  metadata: chunks.map((chunk) => ({ text: chunk.text })),
+});
+```
+
+  </TabItem>
+
+  <TabItem value="elasticsearch" label="ElasticSearch">
+
+```ts title="vector-store.ts" showLineNumbers copy
+import { ElasticSearchVector } from "@mastra/elasticsearch";
+
+const store = new ElasticSearchVector({ url: process.env.ELASTICSEARCH_URL });
+
+await store.createIndex({
+  indexName: "my-collection",
+  dimension: 1536,
+});
+
 await store.upsert({
   indexName: "my-collection",
   vectors: embeddings,
@@ -459,6 +480,20 @@ Each vector database enforces specific naming conventions for indexes and collec
     - Example: `My_Index` is not valid (contains uppercase letters)
     - Example: `_myindex` is not valid (begins with underscore)
   </TabItem>
+  <TabItem value="elasticsearch" label="ElasticSearch">
+    Index names must:
+    - Use only lowercase letters
+    - Not exceed 255 bytes (counting multi-byte characters)
+    - Not begin with underscores, hyphens, or plus signs
+    - Not contain spaces, commas
+    - Not contain special characters (e.g. `:`, `"`, `*`, `+`, `/`, `\`, `|`, `?`, `#`, `>`, `<`)
+    - Not be "." or ".."
+    - Not start with "." (deprecated except for system/hidden indices)
+    - Example: `my-index-123` is valid
+    - Example: `My_Index` is not valid (contains uppercase letters)
+    - Example: `_myindex` is not valid (begins with underscore)
+    - Example: `.myindex` is not valid (begins with dot, deprecated)
+  </TabItem>
   <TabItem value="s3vectors" label="S3 Vectors">
     Index names must:
     - Be unique within the same vector bucket
@@ -496,8 +531,6 @@ The upsert operation:
 - Creates new vectors if they don't exist
 - Automatically handles batching for large datasets
 
-For complete examples of upserting embeddings in different vector stores, see the [Upsert Embeddings](/examples/v1/rag/upsert/upsert-embeddings) guide.
-
 ## Adding Metadata
 
 Vector stores support rich metadata (any JSON-serializable fields) for filtering and organization. Since metadata is stored with no fixed schema, use consistent field naming to avoid unexpected query results.
@@ -536,6 +569,64 @@ Key metadata considerations:
 - Only include fields you plan to filter or sort by - extra fields add overhead
 - Add timestamps (e.g., 'createdAt', 'lastUpdated') to track content freshness
 
+## Deleting Vectors
+
+When building RAG applications, you often need to clean up stale vectors when documents are deleted or updated. Mastra provides the `deleteVectors` method that supports deleting vectors by metadata filters, making it easy to remove all embeddings associated with a specific document.
+
+### Delete by Metadata Filter
+
+The most common use case is deleting all vectors for a specific document when a user deletes it:
+
+```ts title="delete-vectors.ts" showLineNumbers copy
+// Delete all vectors for a specific document
+await store.deleteVectors({
+  indexName: "myCollection",
+  filter: { docId: "document-123" },
+});
+```
+
+This is particularly useful when:
+- A user deletes a document and you need to remove all its chunks
+- You're re-indexing a document and want to remove old vectors first
+- You need to clean up vectors for a specific user or tenant
+
+### Delete Multiple Documents
+
+You can also use complex filters to delete vectors matching multiple conditions:
+
+```ts title="delete-vectors-advanced.ts" showLineNumbers copy
+// Delete all vectors for multiple documents
+await store.deleteVectors({
+  indexName: "myCollection",
+  filter: {
+    docId: { $in: ["doc-1", "doc-2", "doc-3"] },
+  },
+});
+
+// Delete vectors for a specific user's documents
+await store.deleteVectors({
+  indexName: "myCollection",
+  filter: {
+    $and: [
+      { userId: "user-123" },
+      { status: "archived" },
+    ],
+  },
+});
+```
+
+### Delete by Vector IDs
+
+If you have specific vector IDs to delete, you can pass them directly:
+
+```ts title="delete-by-ids.ts" showLineNumbers copy
+// Delete specific vectors by their IDs
+await store.deleteVectors({
+  indexName: "myCollection",
+  ids: ["vec-1", "vec-2", "vec-3"],
+});
+```
+
 ## Best Practices
 
 - Create indexes before bulk insertions