Add Vector Index Guide documentation

[teetangh]

Adds VECTOR_INDEX_GUIDE.md to the repository root.

Covers:

• FTS and GSI service overview
• Search Vector Index, Hyperscale Vector Index, Composite Vector Index specifications
• Comparison table and decision flowchart for choosing the right index
• Terminology mapping (search_based/ vs query_based/ folders)
• Mermaid diagrams for architecture and query flows

[gemini-code-assist]

Summary of Changes

Hello @teetangh, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a comprehensive guide to Couchbase's vector indexing features, designed to help users understand and effectively utilize the different vector index types available. The new documentation clarifies the underlying services (Full Text Search and Global Secondary Index), details the unique characteristics of each vector index, and provides practical guidance through comparison tables and decision flowcharts. This addition aims to streamline the process of selecting and implementing vector search solutions within Couchbase for various AI-driven applications.

Highlights

• New Vector Index Guide: A new documentation file, VECTOR_INDEX_GUIDE.md, has been added to provide a comprehensive guide to Couchbase's vector search capabilities.
• Detailed Index Type Coverage: The guide covers the specifications, architectures, and best use cases for three key vector index types: Search Vector Index, Hyperscale Vector Index, and Composite Vector Index.
• Decision Aids: Included are a comparison table and a decision flowchart to help users choose the most appropriate vector index for their specific needs.
• Terminology Clarification: The document clarifies the mapping of terminology, specifically for search_based/ and query_based/ folders, linking them to the respective vector index types.
• Visual Explanations: Mermaid diagrams are used throughout the guide to visually explain core service overviews, distributed architectures, and query flows for better understanding.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request adds a comprehensive and well-structured guide to Couchbase's vector indexes. The document is detailed, with helpful diagrams and examples that clarify the differences between the various index types. My review focuses on a couple of areas where technical accuracy and clarity could be improved to avoid user confusion. Specifically, I've pointed out an inconsistency in the description of the Search Vector Index filtering mechanism and a statement about folder naming conventions that doesn't align with the current repository structure. Addressing these points will make this excellent guide even more valuable.

[gemini-code-assist]

There's an inconsistency in how hybrid search is described for the Search Vector Index. This diagram suggests that the FTS filter is a pre-filter for the vector search. However, the comparison table on line 453 describes it as a 'Post-filter'. In reality, the underlying mechanism is more of a parallel execution where results are combined and then ranked.

To more accurately represent the hybrid search process, I'd suggest updating the diagram to show parallel execution paths for the FTS filter and the vector search, which then merge for ranking.

Here's a suggestion for the updated diagram:

flowchart LR
    A[Query] --> B(FTS Filter)
    A --> C(Vector Search)
    B --> D{Combine & Rank}
    C --> D
    D --> E[Ranked Results]

Loading

Suggested change

	```mermaid
	flowchart LR
	A[Query] --> B{Has Text/Geo?}
	B -->|Yes| C[FTS Filter]
	B -->|No| D[Vector Search]
	C --> D
	D --> E[Similarity Score]
	E --> F[Ranked Results]
	```
	flowchart LR
	A[Query] --> B(FTS Filter)
	A --> C(Vector Search)
	B --> D{Combine & Rank}
	C --> D
	D --> E[Ranked Results]

[gemini-code-assist]

This section states that the cookbook 'uses' the search_based/ and query_based/ folder naming conventions. However, based on the current repository structure, the folders are still named fts/ and gsi/. This could be confusing for users who are trying to navigate the cookbook based on this guide.

To avoid this confusion, I suggest rephrasing this section to clarify that this is a planned or ongoing transition. A table mapping old names to new names would be very helpful.

Suggested change

	This cookbook uses folder naming conventions that map to vector index types:
	| Folder Name | Index Type | LangChain/Framework Class |
	|-------------|-----------|---------------------------|
	| `search_based/` | Search Vector Index | `CouchbaseSearchVectorStore` |
	| `query_based/` | Hyperscale or Composite Vector Index | `CouchbaseQueryVectorStore` |
	### Historical Context
	The cookbook previously used different terminology:
	- `fts/` (Full Text Search) → now `search_based/`
	- `gsi/` (Global Secondary Index) → now `query_based/`
	The new naming focuses on the *approach* (search-based vs query-based) rather than the underlying service, making it clearer for developers new to Couchbase.
	This cookbook is transitioning to new folder naming conventions to better reflect the underlying search approach. The mapping from the old to the new structure is as follows:
	| New Folder Name | Old Folder Name | Index Type | LangChain/Framework Class |
	|-----------------|-----------------|----------------------------------------|---------------------------------|
	| `search_based/` | `fts/` | Search Vector Index | `CouchbaseSearchVectorStore` |
	| `query_based/` | `gsi/` | Hyperscale or Composite Vector Index | `CouchbaseQueryVectorStore` |
	This change focuses on the *approach* (search-based vs. query-based) rather than the underlying service, making it clearer for developers new to Couchbase.