Update docs examples #271
Update docs examples #271
Conversation
- Add Vector DB guide examples (`search`) - Update JS examples to include required "key" field for `upsert` - Update Vector DB guide to reflect both SDKs return `similarity` field - Remove unnecessary distance-to-similarity conversions - Add note about JS backwards compatibility with `distance` parameter
WalkthroughDocumentation and examples update Vector DB APIs: upsert now requires a per-document Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant App
participant VectorDB
rect rgba(230,245,255,0.6)
note over App,VectorDB: Upsert with explicit per-document keys
App->>VectorDB: upsert([{ key, document|embeddings, metadata }...])
VectorDB-->>App: ack { status, inserted_count }
end
rect rgba(240,255,230,0.6)
note over App,VectorDB: Search returns similarity scores
App->>VectorDB: search({ query|embedding, filters? })
VectorDB-->>App: results[{ id, key?, similarity, ...metadata }]
note right of App: Use result.similarity directly (JS may also include result.distance)
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
Tip 🔌 Remote MCP (Model Context Protocol) integration is now available!Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats. ✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
docs | e72fc7f | Commit Preview URL Branch Preview URL |
Aug 28 2025, 10:55 PM |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
content/SDKs/javascript/examples/index.mdx (1)
359-361: request.trigger is a property, not a functionElsewhere in the API docs,
triggeris shown as a getter (get trigger(): string). Update this example to avoid confusion.- span.setAttribute('trigger', request.trigger()); + span.setAttribute('trigger', request.trigger);content/SDKs/javascript/api-reference.mdx (1)
206-214: Make key required in Upsert docs to match new behavior across SDKsThe Guides state that upsert now requires a
keyfor each document in both SDKs. Here, examples use a key (good), but the textual contract still reads as if a key is optional. Please make the requirement explicit so developers don’t ship non-idempotent upserts.#### upsert `upsert(name: string, ...documents: VectorUpsertParams[]): Promise<string[]>` Inserts or updates vectors in the vector storage. **Parameters** - `name`: The name of the vector storage -- `documents`: One or more documents to upsert, each with either embeddings or text +- `documents`: One or more documents to upsert. Each document must include a unique `key` and either `document` (text) or `embeddings`.Add a concrete type snippet nearby for clarity:
// VectorUpsertParams (JavaScript) interface VectorUpsertParams { key: string; // required, idempotency key for the vector document?: string; // mutually exclusive with embeddings embeddings?: number[]; metadata?: Record<string, Json>; }Also applies to: 216-221
content/Guides/vector-db.mdx (1)
169-185: Correct the JS delete description: delete by key, not by internal IDThe paragraph currently says JavaScript deletes “by IDs.” Per the API reference, JavaScript
deleteaccepts keys. Please align the wording to prevent accidental use of internal IDs that won’t match.-Remove specific vectors from storage using their IDs (JavaScript) or keys (Python). +Remove specific vectors from storage using their keys in both SDKs.
🧹 Nitpick comments (6)
content/SDKs/javascript/examples/index.mdx (2)
112-122: Good addition: stable per-document key; add light validation and stringify for safetyUsing
key: product.idaligns with the new upsert requirements. Consider guarding for missing/empty IDs and normalizing to a string to avoid accidental number/UUID/object keys slipping in from upstream payloads.- // Prepare documents for vector storage - const documents = products.map(product => ({ - key: product.id, + // Prepare documents for vector storage + if (products.some(p => !p?.id)) { + return response.json({ error: 'All products must include a non-empty id' }); + } + const documents = products.map(product => ({ + key: String(product.id), document: product.description, metadata: { id: product.id, name: product.name, price: product.price, category: product.category } }));
147-151: Switch to result.similarity looks correct; consider returning key/id for callersReading
result.similaritydirectly is consistent with the updated API. Small UX upgrade: pass through resultidand/orkeyso consumers can act on a specific vector without digging into metadata.- const formattedResults = results.map(result => ({ - ...result.metadata, - similarity: result.similarity - })); + const formattedResults = results.map(result => ({ + id: result.id, + key: result.key, + ...result.metadata, + similarity: result.similarity, + }));content/SDKs/javascript/api-reference.mdx (1)
291-306: Use “key” terminology consistently in delete examplesDelete takes keys, not internal IDs. The examples use
'id1'etc., which can be misread as internal vector IDs. Rename placeholders to “key” to match the parameter name and the upsert contract.-// Delete a single vector -const deletedCount = await context.vector.delete('product-descriptions', 'id1'); +// Delete a single vector (by key) +const deletedCount = await context.vector.delete('product-descriptions', 'key1'); console.log(`Deleted ${deletedCount} vector(s)`); // Output: Deleted 1 vector(s) // Delete multiple vectors in bulk (more efficient than individual calls) -const deletedCount = await context.vector.delete('product-descriptions', 'id1', 'id2', 'id3'); +const deletedCount = await context.vector.delete('product-descriptions', 'key1', 'key2', 'key3'); console.log(`Deleted ${deletedCount} vector(s)`); // Output: Deleted 3 vector(s) // Delete with array spread -const keysToDelete = ['id1', 'id2', 'id3']; +const keysToDelete = ['key1', 'key2', 'key3']; const deletedCount = await context.vector.delete('product-descriptions', ...keysToDelete); // Handle cases where some vectors might not exist -const deletedCount = await context.vector.delete('product-descriptions', 'existing-id', 'non-existent-id'); +const deletedCount = await context.vector.delete('product-descriptions', 'existing-key', 'non-existent-key'); console.log(`Deleted ${deletedCount} vector(s)`); // Output: Deleted 1 vector(s)content/Guides/vector-db.mdx (3)
47-50: Minor wording tweak for the API links blockTighten phrasing and punctuation to address the lint warnings and improve readability.
-For complete API documentation, see: -- [JavaScript SDK Vector API Reference](/SDKs/javascript/api-reference#vector-storage) -- [Python SDK Vector API Reference](/SDKs/python/api-reference#vector-storage) +For complete API documentation, see: +- [JavaScript SDK Vector API Reference](/SDKs/javascript/api-reference#vector-storage) +- [Python SDK Vector API Reference](/SDKs/python/api-reference#vector-storage)
206-264: RAG example: handle missing metadata text more defensively and include keysSome datasets won’t store raw content in metadata. Suggest defaulting to an empty string and including
id/keyin the returned sources to improve traceability.- const contextTexts = searchResults.map(result => - result.metadata.content || result.metadata.text - ); + const contextTexts = searchResults.map(result => + result.metadata?.content ?? result.metadata?.text ?? '' + ); @@ - sources: searchResults.map(r => ({ - id: r.id, - title: r.metadata.title, - similarity: r.similarity - })) + sources: searchResults.map(r => ({ + id: r.id, + key: r.key, + title: r.metadata?.title, + similarity: r.similarity, + }))
339-386: Product search example is solid; small scoring nitMultiplying by 1.2 for exact category matches is clear. Consider clamping the final score to [0, 1.2] if downstream assumes a 0–1 range.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (3)
content/Guides/vector-db.mdx(5 hunks)content/SDKs/javascript/api-reference.mdx(1 hunks)content/SDKs/javascript/examples/index.mdx(2 hunks)
🧰 Additional context used
🪛 LanguageTool
content/Guides/vector-db.mdx
[grammar] ~47-~47: There might be a mistake here.
Context: ...PI For complete API documentation, see: - [JavaScript SDK Vector API Reference](/SD...
(QB_NEW_EN)
[grammar] ~48-~48: There might be a mistake here.
Context: ...: - JavaScript SDK Vector API Reference - [Python SDK Vector API Reference](/SDKs/p...
(QB_NEW_EN)
[grammar] ~55-~55: There might be a mistake here.
Context: ...omputed embeddings. SDK Requirements: - Both SDKs: Require key field for eac...
(QB_NEW_EN)
[grammar] ~141-~141: There might be a mistake here.
Context: ...log(Similarity: ${result.similarity}); }); python # Python # Semantic s...
(QB_NEW_EN)
[grammar] ~198-~198: There might be a mistake here.
Context: ...l Examples For more code examples, see: - [JavaScript SDK Examples](/SDKs/javascrip...
(QB_NEW_EN)
[grammar] ~199-~199: There might be a mistake here.
Context: ...xamples, see: - JavaScript SDK Examples - [Python SDK Examples](/SDKs/python/exampl...
(QB_NEW_EN)
[grammar] ~206-~206: There might be a mistake here.
Context: ...t/TypeScript - Simple RAG implementation import { AgentHandler } from '@agentuity...
(QB_NEW_EN)
[grammar] ~209-~209: There might be a mistake here.
Context: ... async (request, response, context) => { const { question } = await request.data....
(QB_NEW_EN)
[grammar] ~256-~256: There might be a mistake here.
Context: ... })) }); } catch (error) { context.logger.error('RAG query failed:'...
(QB_NEW_EN)
[grammar] ~262-~262: There might be a mistake here.
Context: ... details: error.message }); } }; export default handler;} py={# Pyt...
(QB_NEW_EN)
[grammar] ~265-~265: There might be a mistake here.
Context: ...y={`# Python - Simple RAG implementation from agentuity import AgentRequest, Agen...
(QB_NEW_EN)
[grammar] ~268-~268: There might be a mistake here.
Context: ...: AgentResponse, context: AgentContext): data = await request.data.json() que...
(QB_NEW_EN)
[grammar] ~328-~328: There might be a mistake here.
Context: ...": str(e) })`} /> Key Points: - Semantic search finds relevant documen...
(QB_NEW_EN)
[grammar] ~339-~339: There might be a mistake here.
Context: ...TypeScript - Product search with filters import { AgentHandler } from '@agentuity...
(QB_NEW_EN)
[grammar] ~342-~342: There might be a mistake here.
Context: ... async (request, response, context) => { const { query, maxPrice, category, inSto...
(QB_NEW_EN)
[grammar] ~345-~345: There might be a mistake here.
Context: ... = await request.data.json(); try { // Build metadata filters based on crite...
(QB_NEW_EN)
[grammar] ~378-~378: There might be a mistake here.
Context: ...results }); } catch (error) { context.logger.error('Product search fai...
(QB_NEW_EN)
[grammar] ~384-~384: There might be a mistake here.
Context: ...failed', products: [] }); } }; export default handler;} py={# Pyt...
(QB_NEW_EN)
[grammar] ~387-~387: There might be a mistake here.
Context: ...{`# Python - Product search with filters from agentuity import AgentRequest, Agen...
(QB_NEW_EN)
[grammar] ~390-~390: There might be a mistake here.
Context: ...: AgentResponse, context: AgentContext): data = await request.data.json() que...
(QB_NEW_EN)
[grammar] ~446-~446: There might be a mistake here.
Context: ...": [] })`} /> Key Techniques: - Metadata filters are applied at the ve...
(QB_NEW_EN)
[grammar] ~454-~454: There might be a mistake here.
Context: ...ls & Solutions ### Empty Search Results Problem: Your search returns empty res...
(QB_NEW_EN)
[grammar] ~457-~457: There might be a mistake here.
Context: ...gh relevant data exists. Solutions: - Lower the similarity threshold: Start ...
(QB_NEW_EN)
[grammar] ~478-~478: There might be a mistake here.
Context: ....5 }); } ``` ### Duplicate Documents Problem: Same content appears multiple...
(QB_NEW_EN)
[grammar] ~481-~481: There might be a mistake here.
Context: ...t is idempotent when using the same key: - Always use consistent key values for y...
(QB_NEW_EN)
[grammar] ~486-~486: There might be a mistake here.
Context: ...ur storage clean ### Performance Issues Problem: Vector operations take too lo...
(QB_NEW_EN)
[grammar] ~489-~489: There might be a mistake here.
Context: ...perations take too long. Solutions: - Batch operations: Upsert 100-500 docum...
(QB_NEW_EN)
[grammar] ~494-~494: There might be a mistake here.
Context: ...d focused ### Irrelevant Search Results Problem: Search returns irrelevant or ...
(QB_NEW_EN)
[grammar] ~497-~497: There might be a mistake here.
Context: ...or unexpected documents. Solutions: - Check similarity scores: Results with ...
(QB_NEW_EN)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Workers Builds: docs
🔇 Additional comments (3)
content/Guides/vector-db.mdx (3)
70-90: Keys added in upsert examples are correct and make operations idempotentUsing explicit
keyvalues in both text and embedding upserts is aligned with the API and the idempotency guidance below.
138-142: Result processing uses similarity directly — goodSwitching logs to
result.similarityremoves confusion and avoids client-side transformations from distance.
196-201: Cross-links to example sections are helpfulLinks to example sections for JS/Python are a nice touch and make the flow discoverable.
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
content/Guides/vector-db.mdx (1)
167-170: Good fix: clarified distance as a legacy result fieldThis resolves the earlier ambiguity. It now clearly states that
distanceis returned (not a query parameter) and thatsimilarityis preferred.
🧹 Nitpick comments (9)
content/Guides/vector-db.mdx (9)
55-56: Minor grammar: add an article for clarity“Require
keyfield” → “Require akeyfield”.Apply this diff:
-**SDK Requirements:** -- **Both SDKs**: Require `key` field for each document +**SDK Requirements:** +- **Both SDKs**: Require a `key` field for each document
65-77: Confirm JS upsert parameter shape; prefer array for multiple documentsThe JS example passes multiple document objects as separate arguments. If the SDK expects an array (which is common and matches the Python example), this will mislead users.
If the SDK accepts an array, update to this:
-const ids = await context.vector.upsert( - 'knowledge-base', - { - key: 'doc-1', - document: 'Agentuity is an agent-native cloud platform', - metadata: { category: 'platform', source: 'docs' } - }, - { - key: 'doc-2', - document: 'Vector storage enables semantic search capabilities', - metadata: { category: 'features', source: 'docs' } - } -); +const ids = await context.vector.upsert( + 'knowledge-base', + [ + { + key: 'doc-1', + document: 'Agentuity is an agent-native cloud platform', + metadata: { category: 'platform', source: 'docs' } + }, + { + key: 'doc-2', + document: 'Vector storage enables semantic search capabilities', + metadata: { category: 'features', source: 'docs' } + } + ] +);If varargs are intentionally supported, consider adding a brief note: “You can pass one or more document objects or an array of documents.”
79-87: Consistency nit: key naming style differs across examplesJS uses hyphens (embedding-1) while Python uses underscores (embedding_1). Mixing styles can distract readers.
Consider standardizing on one style (hyphens or underscores) across all examples in this guide.
167-170: Document result identifiers alongside similarityExamples below use
result.idandresult.key, but the “Search Results” bullets don’t mention them. Add these to set reader expectations.Apply this diff:
**Search Results:** -- **Both SDKs**: Return results with `similarity` field (1.0 = perfect match, 0.0 = no match) +- **Both SDKs**: Return results with `similarity` field (1.0 = perfect match, 0.0 = no match) +- **Both SDKs**: Include `id` (internal vector ID) and `key` (your document key) on each result - **Note**: The JavaScript SDK also returns a `distance` field for backward compatibility; prefer `similarity`
173-186: Clarify delete signatures; consider array form for bulk deleteThe JS bulk delete shows multiple string arguments. Verify if the SDK prefers an array (common in REST/SDKs). If arrays are accepted, use them for clarity and parity with upsert examples.
// Delete single vector -const deletedCount = await context.vector.delete('knowledge-base', 'doc-1'); +const deletedCount = await context.vector.delete('knowledge-base', 'doc-1'); // Delete multiple vectors -const bulkDeleteCount = await context.vector.delete( - 'knowledge-base', - 'doc-1', 'doc-2', 'doc-3' -); +const bulkDeleteCount = await context.vector.delete( + 'knowledge-base', + ['doc-1', 'doc-2', 'doc-3'] +);Also consider documenting the return value precisely: “delete returns the number of deleted vectors.”
231-236: Defensive context assembly: includedocumentfallback and avoid empty entriesSome results may lack metadata.content/text; include
result.documentas a fallback and drop empty strings. Optionally cap the assembled context length.- const contextTexts = searchResults.map(result => - result.metadata?.content ?? result.metadata?.text ?? '' - ); - const assembledContext = contextTexts.join('\n\n'); + const contextTexts = searchResults + .map(r => r.metadata?.content ?? r.metadata?.text ?? r.document ?? '') + .filter(Boolean); + const assembledContext = contextTexts.join('\n\n').slice(0, 4000);
252-257: Minor: results schema consistencyYou return
id,key,title,similarity. Iftitlemay be absent, consider defaulting tometadata.sourceor omitting undefined fields to keep payload tidy.- title: r.metadata?.title, + title: r.metadata?.title ?? r.metadata?.source,Alternatively, filter falsy properties before returning.
460-471: Unify instance name: use “knowledge-base” consistentlyEarlier examples use 'knowledge-base'; this snippet uses 'kb'. Consistency helps readers.
-let results = await context.vector.search('kb', { +let results = await context.vector.search('knowledge-base', { query, similarity: 0.8 }); if (results.length === 0) { // Try again with lower threshold - results = await context.vector.search('kb', { + results = await context.vector.search('knowledge-base', { query, similarity: 0.5 }); }
95-115: Minor consistency: key naming style across languagesJS uses
doc-1, Python usesdoc_1. Consider aligning the naming to reduce cognitive friction.No code changes required; a brief note near the first upsert example is sufficient: “Keys can include hyphens or underscores; this guide uses hyphens consistently.”
Also applies to: 111-114
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (3)
content/Guides/vector-db.mdx(6 hunks)content/SDKs/javascript/api-reference.mdx(2 hunks)content/SDKs/javascript/examples/index.mdx(2 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- content/SDKs/javascript/api-reference.mdx
- content/SDKs/javascript/examples/index.mdx
🧰 Additional context used
🪛 LanguageTool
content/Guides/vector-db.mdx
[grammar] ~47-~47: There might be a mistake here.
Context: ...PI For complete API documentation, see: - [JavaScript SDK Vector API Reference](/SD...
(QB_NEW_EN)
[grammar] ~48-~48: There might be a mistake here.
Context: ...: - JavaScript SDK Vector API Reference - [Python SDK Vector API Reference](/SDKs/p...
(QB_NEW_EN)
[grammar] ~55-~55: There might be a mistake here.
Context: ...omputed embeddings. SDK Requirements: - Both SDKs: Require key field for eac...
(QB_NEW_EN)
[grammar] ~139-~139: There might be a mistake here.
Context: ...log(Similarity: ${result.similarity}); }); python # Python # Semantic s...
(QB_NEW_EN)
[grammar] ~167-~167: There might be a mistake here.
Context: ...adata key-value pairs Search Results: - Both SDKs: Return results with `simila...
(QB_NEW_EN)
[grammar] ~182-~182: There might be a mistake here.
Context: ..., 'doc-1'); // Delete multiple vectors const bulkDeleteCount = await context.ve...
(QB_NEW_EN)
[grammar] ~183-~183: There might be a mistake here.
Context: ...leteCount = await context.vector.delete( 'knowledge-base', 'doc-1', 'doc-2', '...
(QB_NEW_EN)
[grammar] ~185-~185: There might be a mistake here.
Context: ...edge-base', 'doc-1', 'doc-2', 'doc-3' ); python # Python # Delete sing...
(QB_NEW_EN)
[grammar] ~201-~201: There might be a mistake here.
Context: ...l Examples For more code examples, see: - [JavaScript SDK Examples](/SDKs/javascrip...
(QB_NEW_EN)
[grammar] ~202-~202: There might be a mistake here.
Context: ...xamples, see: - JavaScript SDK Examples - [Python SDK Examples](/SDKs/python/exampl...
(QB_NEW_EN)
[grammar] ~209-~209: There might be a mistake here.
Context: ...t/TypeScript - Simple RAG implementation import { AgentHandler } from '@agentuity...
(QB_NEW_EN)
[grammar] ~212-~212: There might be a mistake here.
Context: ... async (request, response, context) => { const { question } = await request.data....
(QB_NEW_EN)
[grammar] ~260-~260: There might be a mistake here.
Context: ... })) }); } catch (error) { context.logger.error('RAG query failed:'...
(QB_NEW_EN)
[grammar] ~266-~266: There might be a mistake here.
Context: ... details: error.message }); } }; export default handler;} py={# Pyt...
(QB_NEW_EN)
[grammar] ~269-~269: There might be a mistake here.
Context: ...y={`# Python - Simple RAG implementation from agentuity import AgentRequest, Agen...
(QB_NEW_EN)
[grammar] ~272-~272: There might be a mistake here.
Context: ...: AgentResponse, context: AgentContext): data = await request.data.json() que...
(QB_NEW_EN)
[grammar] ~332-~332: There might be a mistake here.
Context: ...": str(e) })`} /> Key Points: - Semantic search finds relevant documen...
(QB_NEW_EN)
[grammar] ~343-~343: There might be a mistake here.
Context: ...TypeScript - Product search with filters import { AgentHandler } from '@agentuity...
(QB_NEW_EN)
[grammar] ~346-~346: There might be a mistake here.
Context: ... async (request, response, context) => { const { query, maxPrice, category, inSto...
(QB_NEW_EN)
[grammar] ~349-~349: There might be a mistake here.
Context: ... = await request.data.json(); try { // Build metadata filters based on crite...
(QB_NEW_EN)
[grammar] ~379-~379: There might be a mistake here.
Context: ...results }); } catch (error) { context.logger.error('Product search fai...
(QB_NEW_EN)
[grammar] ~385-~385: There might be a mistake here.
Context: ...failed', products: [] }); } }; export default handler;} py={# Pyt...
(QB_NEW_EN)
[grammar] ~388-~388: There might be a mistake here.
Context: ...{`# Python - Product search with filters from agentuity import AgentRequest, Agen...
(QB_NEW_EN)
[grammar] ~391-~391: There might be a mistake here.
Context: ...: AgentResponse, context: AgentContext): data = await request.data.json() que...
(QB_NEW_EN)
[grammar] ~443-~443: There might be a mistake here.
Context: ...": [] })`} /> Key Techniques: - Metadata filters are applied at the ve...
(QB_NEW_EN)
[grammar] ~450-~450: There might be a mistake here.
Context: ...ls & Solutions ### Empty Search Results Problem: Your search returns empty res...
(QB_NEW_EN)
[grammar] ~453-~453: There might be a mistake here.
Context: ...gh relevant data exists. Solutions: - Lower the similarity threshold: Start ...
(QB_NEW_EN)
[grammar] ~474-~474: There might be a mistake here.
Context: ....5 }); } ``` ### Duplicate Documents Problem: Same content appears multiple...
(QB_NEW_EN)
[grammar] ~477-~477: There might be a mistake here.
Context: ...t is idempotent when using the same key: - Always use consistent key values for y...
(QB_NEW_EN)
[grammar] ~482-~482: There might be a mistake here.
Context: ...ur storage clean ### Performance Issues Problem: Vector operations take too lo...
(QB_NEW_EN)
[grammar] ~485-~485: There might be a mistake here.
Context: ...perations take too long. Solutions: - Batch operations: Upsert 100-500 docum...
(QB_NEW_EN)
[grammar] ~490-~490: There might be a mistake here.
Context: ...d focused ### Irrelevant Search Results Problem: Search returns irrelevant or ...
(QB_NEW_EN)
[grammar] ~493-~493: There might be a mistake here.
Context: ...or unexpected documents. Solutions: - Check similarity scores: Results with ...
(QB_NEW_EN)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Workers Builds: docs
🔇 Additional comments (3)
content/Guides/vector-db.mdx (3)
524-524: Cross-guide links validatedThe referenced guide files both exist with correct casing:
- content/Guides/key-value.mdx
- content/Guides/agent-communication.mdx
No broken links detected.
47-50: Please verify API Reference pages and “Vector Storage” anchorsI ran the grep across your content directory and saw the API Reference links in the SDK index files, but I wasn’t able to locate the actual
api-referencepage files or a “## Vector Storage” heading within them. Before merging, broken doc links could confuse users, so please double-check:
- That a file exists at
•content/SDKs/javascript/api-reference/index.mdx(orcontent/SDKs/javascript/api-reference.mdx)
and contains a third-level heading exactly matching## Vector Storage(to generate the#vector-storageanchor).- That a file exists at
•content/SDKs/python/api-reference/index.mdx(orcontent/SDKs/python/api-reference.mdx)
and likewise includes a## Vector Storageheading for the#vector-storageanchor.Once you’ve confirmed (or corrected) the file paths and headings, you can resolve this comment.
199-204: Example links validatedBoth SDK example pages include the expected sections and matching anchors:
- JavaScript SDK Examples
The filecontent/SDKs/javascript/examples/index.mdxcontains a heading## Vector Storage Usage, which slugifies tovector-storage-usageand matches the link/SDKs/javascript/examples#vector-storage-usage.- Python SDK Examples
The filecontent/SDKs/python/examples/index.mdxincludes a heading## Vector Storage, which slugifies tovector-storageand matches the link/SDKs/python/examples#vector-storage.All links are present and correct.
| const filteredResults = searchResults | ||
| .filter(result => !maxPrice || result.metadata.price <= maxPrice) | ||
| .map(result => ({ | ||
| ...result.metadata, | ||
| similarity: result.similarity | ||
| })) | ||
| .sort((a, b) => b.similarity - a.similarity); | ||
There was a problem hiding this comment.
Fix maxPrice filter edge case (0 and falsy values)
The current check uses !maxPrice, which treats 0 as “no filter” and may include overpriced items. Also guard against missing price.
Apply:
- const filteredResults = searchResults
- .filter(result => !maxPrice || result.metadata.price <= maxPrice)
+ const filteredResults = searchResults
+ .filter(r => maxPrice == null || (typeof r.metadata?.price === 'number' && r.metadata.price <= maxPrice))
.map(result => ({
...result.metadata,
similarity: result.similarity
}))
.sort((a, b) => b.similarity - a.similarity);📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| const filteredResults = searchResults | |
| .filter(result => !maxPrice || result.metadata.price <= maxPrice) | |
| .map(result => ({ | |
| ...result.metadata, | |
| similarity: result.similarity | |
| })) | |
| .sort((a, b) => b.similarity - a.similarity); | |
| const filteredResults = searchResults | |
| .filter(r => maxPrice == null || (typeof r.metadata?.price === 'number' && r.metadata.price <= maxPrice)) | |
| .map(result => ({ | |
| ...result.metadata, | |
| similarity: result.similarity | |
| })) | |
| .sort((a, b) => b.similarity - a.similarity); |
🤖 Prompt for AI Agents
In content/Guides/vector-db.mdx around lines 364 to 371, the maxPrice check uses
!maxPrice which treats 0 as "no filter" and doesn't guard against missing price;
change the filter logic to treat undefined/null maxPrice as "no filter" but
apply the numeric comparison when maxPrice is provided, and also ensure items
with missing price are excluded when a maxPrice is specified (e.g., check
maxPrice == null to allow zero, and require result.metadata.price != null before
comparing).
| if max_price and result.metadata.get("price", 0) > max_price: | ||
| continue | ||
There was a problem hiding this comment.
Python: same max_price falsy bug as JS; use explicit None check
If max_price is 0, the current condition skips filtering. Use is not None.
- if max_price and result.metadata.get("price", 0) > max_price:
+ if max_price is not None and result.metadata.get("price", 0) > max_price:
continue📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| if max_price and result.metadata.get("price", 0) > max_price: | |
| continue | |
| if max_price is not None and result.metadata.get("price", 0) > max_price: | |
| continue |
🤖 Prompt for AI Agents
In content/Guides/vector-db.mdx around lines 419 to 421, the price filter uses a
falsy check ("if max_price and ...") which incorrectly ignores a valid max_price
of 0; replace the truthy check with an explicit None check so the condition
reads: if max_price is not None and result.metadata.get("price", 0) > max_price:
continue, ensuring zero is treated as a valid limit.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
content/Guides/vector-db.mdx (2)
363-371: Fix JS price filter: handle 0 and missing/null prices correctly.Current
!maxPricetreats 0 as “no filter” and doesn’t guard missing price.Apply:
- const filteredResults = searchResults - .filter(result => !maxPrice || result.metadata.price <= maxPrice) + const filteredResults = searchResults + .filter(r => maxPrice == null || (typeof r.metadata?.price === 'number' && r.metadata.price <= maxPrice)) .map(result => ({ ...result.metadata, similarity: result.similarity })) .sort((a, b) => b.similarity - a.similarity);
419-424: Fix Python price filter: treat 0 as valid and guard non-numeric/missing price.Truthiness check skips filtering when
max_price=0; also compare only when price is numeric.Apply:
- if max_price and result.metadata.get("price", 0) > max_price: - continue + price = result.metadata.get("price") + if max_price is not None: + if not isinstance(price, (int, float)): + continue + if price > max_price: + continue
🧹 Nitpick comments (4)
content/Guides/vector-db.mdx (4)
136-140: Harden result logging against missing metadata.Accessing
result.metadata.sourcecan throw ifmetadatais absent.Apply:
- console.log(`Found: ${result.metadata.source}`); - console.log(`Similarity: ${result.similarity}`); + console.log(`Found: ${result.metadata?.source ?? 'unknown'}`); + console.log(`Similarity: ${result.similarity}`);
95-103: Unify key style across JS/Python examples.Docs mix
doc-1(JS) anddoc_1(Python). Use one style to reduce confusion.Apply:
- "key": "doc_1", # Required: unique identifier for this vector + "key": "doc-1", # Required: unique identifier for this vector ... - "key": "doc_2", # Required: unique identifier for this vector + "key": "doc-2", # Required: unique identifier for this vector ... - "key": "embedding_1", # Required: unique identifier for this vector + "key": "embedding-1", # Required: unique identifier for this vectorAlso applies to: 100-103, 111-114
58-60: Call out key uniqueness scope (per storage instance).Readers benefit from knowing the uniqueness boundary for idempotency.
Apply:
The upsert operation is idempotent - upserting with an existing key updates the existing vector rather than creating a duplicate. The same internal vector ID is reused, ensuring your vector storage remains clean and efficient. +Keys must be unique within a given vector storage instance; reusing a key in the same instance updates that vector.
246-248: Optional: reduce ambiguity around placeholder LLM calls.Add a one-line stub or comment so readers know
generateAnswer/generate_answerare placeholders.Apply (JS shown; mirror in Python):
- // Use your preferred LLM here (OpenAI, Anthropic, etc.) - const llmResponse = await generateAnswer(prompt); + // Placeholder: implement with your preferred LLM client + const llmResponse = await generateAnswer(prompt); // user-definedAlso applies to: 308-310
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
content/Guides/vector-db.mdx(6 hunks)
🧰 Additional context used
🪛 LanguageTool
content/Guides/vector-db.mdx
[grammar] ~47-~47: There might be a mistake here.
Context: ...PI For complete API documentation, see: - [JavaScript SDK Vector API Reference](/SD...
(QB_NEW_EN)
[grammar] ~48-~48: There might be a mistake here.
Context: ...: - JavaScript SDK Vector API Reference - [Python SDK Vector API Reference](/SDKs/p...
(QB_NEW_EN)
[grammar] ~55-~55: There might be a mistake here.
Context: ...omputed embeddings. SDK Requirements: - Both SDKs: Require a key field for e...
(QB_NEW_EN)
[grammar] ~139-~139: There might be a mistake here.
Context: ...log(Similarity: ${result.similarity}); }); python # Python # Semantic s...
(QB_NEW_EN)
[grammar] ~167-~167: There might be a mistake here.
Context: ...adata key-value pairs Search Results: - Both SDKs: Return results with `simila...
(QB_NEW_EN)
[grammar] ~182-~182: There might be a mistake here.
Context: ..., 'doc-1'); // Delete multiple vectors const bulkDeleteCount = await context.ve...
(QB_NEW_EN)
[grammar] ~183-~183: There might be a mistake here.
Context: ...leteCount = await context.vector.delete( 'knowledge-base', 'doc-1', 'doc-2', '...
(QB_NEW_EN)
[grammar] ~185-~185: There might be a mistake here.
Context: ...edge-base', 'doc-1', 'doc-2', 'doc-3' ); python # Python # Delete sing...
(QB_NEW_EN)
[grammar] ~201-~201: There might be a mistake here.
Context: ...l Examples For more code examples, see: - [JavaScript SDK Examples](/SDKs/javascrip...
(QB_NEW_EN)
[grammar] ~202-~202: There might be a mistake here.
Context: ...xamples, see: - JavaScript SDK Examples - [Python SDK Examples](/SDKs/python/exampl...
(QB_NEW_EN)
[grammar] ~209-~209: There might be a mistake here.
Context: ...t/TypeScript - Simple RAG implementation import { AgentHandler } from '@agentuity...
(QB_NEW_EN)
[grammar] ~212-~212: There might be a mistake here.
Context: ... async (request, response, context) => { const { question } = await request.data....
(QB_NEW_EN)
[grammar] ~260-~260: There might be a mistake here.
Context: ... })) }); } catch (error) { context.logger.error('RAG query failed:'...
(QB_NEW_EN)
[grammar] ~266-~266: There might be a mistake here.
Context: ... details: error.message }); } }; export default handler;} py={# Pyt...
(QB_NEW_EN)
[grammar] ~269-~269: There might be a mistake here.
Context: ...y={`# Python - Simple RAG implementation from agentuity import AgentRequest, Agen...
(QB_NEW_EN)
[grammar] ~272-~272: There might be a mistake here.
Context: ...: AgentResponse, context: AgentContext): data = await request.data.json() que...
(QB_NEW_EN)
[grammar] ~332-~332: There might be a mistake here.
Context: ...": str(e) })`} /> Key Points: - Semantic search finds relevant documen...
(QB_NEW_EN)
[grammar] ~343-~343: There might be a mistake here.
Context: ...TypeScript - Product search with filters import { AgentHandler } from '@agentuity...
(QB_NEW_EN)
[grammar] ~346-~346: There might be a mistake here.
Context: ... async (request, response, context) => { const { query, maxPrice, category, inSto...
(QB_NEW_EN)
[grammar] ~349-~349: There might be a mistake here.
Context: ... = await request.data.json(); try { // Build metadata filters based on crite...
(QB_NEW_EN)
[grammar] ~379-~379: There might be a mistake here.
Context: ...results }); } catch (error) { context.logger.error('Product search fai...
(QB_NEW_EN)
[grammar] ~385-~385: There might be a mistake here.
Context: ...failed', products: [] }); } }; export default handler;} py={# Pyt...
(QB_NEW_EN)
[grammar] ~388-~388: There might be a mistake here.
Context: ...{`# Python - Product search with filters from agentuity import AgentRequest, Agen...
(QB_NEW_EN)
[grammar] ~391-~391: There might be a mistake here.
Context: ...: AgentResponse, context: AgentContext): data = await request.data.json() que...
(QB_NEW_EN)
[grammar] ~443-~443: There might be a mistake here.
Context: ...": [] })`} /> Key Techniques: - Metadata filters are applied at the ve...
(QB_NEW_EN)
[grammar] ~450-~450: There might be a mistake here.
Context: ...ls & Solutions ### Empty Search Results Problem: Your search returns empty res...
(QB_NEW_EN)
[grammar] ~453-~453: There might be a mistake here.
Context: ...gh relevant data exists. Solutions: - Lower the similarity threshold: Start ...
(QB_NEW_EN)
[grammar] ~474-~474: There might be a mistake here.
Context: ....5 }); } ``` ### Duplicate Documents Problem: Same content appears multiple...
(QB_NEW_EN)
[grammar] ~477-~477: There might be a mistake here.
Context: ...t is idempotent when using the same key: - Always use consistent key values for y...
(QB_NEW_EN)
[grammar] ~482-~482: There might be a mistake here.
Context: ...ur storage clean ### Performance Issues Problem: Vector operations take too lo...
(QB_NEW_EN)
[grammar] ~485-~485: There might be a mistake here.
Context: ...perations take too long. Solutions: - Batch operations: Upsert 100-500 docum...
(QB_NEW_EN)
[grammar] ~490-~490: There might be a mistake here.
Context: ...d focused ### Irrelevant Search Results Problem: Search returns irrelevant or ...
(QB_NEW_EN)
[grammar] ~493-~493: There might be a mistake here.
Context: ...or unexpected documents. Solutions: - Check similarity scores: Results with ...
(QB_NEW_EN)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Workers Builds: docs
🔇 Additional comments (1)
content/Guides/vector-db.mdx (1)
167-170: Good clarification on similarity vs. distance.Clear that
similarityis primary anddistanceis a legacy result field in JS. Nice.
Summary by CodeRabbit