Skip to content

Enhance vector search API reference documentation #226

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 8, 2025
Merged

Enhance vector search API reference documentation #226

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 24 additions & 7 deletions content/SDKs/javascript/api-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,26 +218,43 @@ Searches for vectors in the vector storage.
##### Parameters

- `name`: The name of the vector storage
- `params`: Search parameters including query, limit, similarity threshold, and metadata filters
- `params`: Search parameters object with the following properties:
- `query` (string, required): The text query to search for. This will be converted to embeddings and used to find semantically similar documents.
- `limit` (number, optional): Maximum number of search results to return. Must be a positive integer. If not specified, the server default will be used.
- `similarity` (number, optional): Minimum similarity threshold for results (0.0-1.0). Only vectors with similarity scores greater than or equal to this value will be returned. 1.0 means exact match, 0.0 means no similarity requirement.
- `metadata` (object, optional): Metadata filters to apply to the search. Only vectors whose metadata matches all specified key-value pairs will be included in results. Must be a valid JSON object.

Comment on lines +221 to 226
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Mention non-empty query requirement & tighten grammar

  1. The backend rejects an empty string for query (see learning from Agentuity PR QA Agent Interface #208). Add an explicit note or throw if query.trim().length === 0.
  2. Minor grammar tweaks:
    • "query … This will be converted to embeddings"
    • "metadata … will be included in the results."
-  - `query` (string, required): The text query to search for. This will be converted to embeddings and used to find semantically similar documents.
+  - `query` (string, required): The text query to search for (must be **non-empty**; use a single space `" "` for metadata-only searches). This query is converted to embeddings and used to find semantically similar documents.
...
-  - `metadata` (object, optional): Metadata filters to apply to the search. Only vectors whose metadata matches all specified key-value pairs will be included in results. Must be a valid JSON object.
+  - `metadata` (object, optional): Metadata filters to apply to the search. Only vectors whose metadata matches all specified key-value pairs will be included in **the** results. Must be a valid JSON object.
📝 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.

Suggested change
- `params`: Search parameters object with the following properties:
- `query` (string, required): The text query to search for. This will be converted to embeddings and used to find semantically similar documents.
- `limit` (number, optional): Maximum number of search results to return. Must be a positive integer. If not specified, the server default will be used.
- `similarity` (number, optional): Minimum similarity threshold for results (0.0-1.0). Only vectors with similarity scores greater than or equal to this value will be returned. 1.0 means exact match, 0.0 means no similarity requirement.
- `metadata` (object, optional): Metadata filters to apply to the search. Only vectors whose metadata matches all specified key-value pairs will be included in results. Must be a valid JSON object.
- `params`: Search parameters object with the following properties:
- `query` (string, required): The text query to search for (must be **non-empty**; use a single space `" "` for metadata-only searches). This query is converted to embeddings and used to find semantically similar documents.
- `limit` (number, optional): Maximum number of search results to return. Must be a positive integer. If not specified, the server default will be used.
- `similarity` (number, optional): Minimum similarity threshold for results (0.0-1.0). Only vectors with similarity scores greater than or equal to this value will be returned. 1.0 means exact match, 0.0 means no similarity requirement.
- `metadata` (object, optional): Metadata filters to apply to the search. Only vectors whose metadata matches all specified key-value pairs will be included in **the** results. Must be a valid JSON object.
🧰 Tools
🪛 LanguageTool

[grammar] ~222-~222: “Text” is a singular noun. It appears that the verb form is incorrect.
Context: ... - query (string, required): The text query to search for. This will be converted t...

(PCT_SINGULAR_NOUN_PLURAL_VERB_AGREEMENT)

[uncategorized] ~225-~225: You might be missing the article “the” here.
Context: ...ied key-value pairs will be included in results. Must be a valid JSON object. ##### Re...

(AI_EN_LECTOR_MISSING_DETERMINER_THE)

🤖 Prompt for AI Agents 
In content/SDKs/javascript/api-reference.mdx around lines 221 to 226, update the
description of the `query` parameter to explicitly state that it must be a
non-empty string and that empty or whitespace-only strings are rejected by the
backend. Also, adjust the grammar by changing "This will be converted" to "This
text will be converted" for `query`, and add "the" before "results" in the
`metadata` description to improve clarity.

##### Return Value

Returns a Promise that resolves to an array of search results, each containing an ID, metadata, and distance score.
Returns a Promise that resolves to an array of search results, each containing an ID, key, metadata, and similarity score.

##### Example
##### Examples

```typescript
// Search for similar products
// Basic search with query only
const results = await context.vector.search('product-descriptions', {
query: 'comfortable office chair'
});

// Search with limit and similarity threshold
const results = await context.vector.search('product-descriptions', {
query: 'comfortable office chair',
limit: 5,
similarity: 0.7,
metadata: { category: 'furniture' }
similarity: 0.7
});

// Search with metadata filtering
const results = await context.vector.search('product-descriptions', {
query: 'comfortable office chair',
limit: 10,
similarity: 0.6,
metadata: { category: 'furniture', inStock: true }
});

// Process search results
for (const result of results) {
console.log(`Product ID: ${result.id}, Similarity: ${result.distance}`);
console.log(`Product ID: ${result.id}, Similarity: ${result.similarity}`);
console.log(`Key: ${result.key}`);
console.log(`Metadata: ${JSON.stringify(result.metadata)}`);
}
```
Expand Down