All chapters
  1. Start hereRetrieval is a query. The model reads only what it returns
  2. Foundations · 1What retrieval means: lookup, keyword search, semantic search
  3. Foundations · 2Traditional SQL first: WHERE, indexes, full-text search and BM25
  4. Foundations · 3Vectors without AI: coordinates, distance and nearest neighbors
  5. Foundations · 4Embeddings: how a model turns text into a vector
  6. Foundations · 5Choosing an embedding model: quality, cost, privacy and fit
  7. Search · 6Schema and storage: where the vectors live
  8. Search · 7Exact vector search: compare the query with every row
  9. Search · 8Approximate nearest neighbors: HNSW, IVF and the recall trade
  10. Search · 9PostgreSQL and pgvector: vectors inside a relational database
  11. Search · 10SQLite vector search: one file on one machine
  12. Pipeline · 11Chunking and ingestion: from a document to retrievable units
  13. Pipeline · 12Retrieval pipelines: from a question to the context the model reads
  14. Pipeline · 13Hybrid search: words and vectors together
  15. Pipeline · 14Reranking: a second, more careful look at the candidates
  16. Pipeline · 15Top-k and scale: ten thousand, a hundred thousand, a million rows
  17. Pipeline · 16Two corpora: similar applicants and underwriter precedents
  18. Pipeline · 17Grounded generation: citations, abstention and conflicts
  19. Pipeline · 18Evaluating retrieval: recall@k, MRR, nDCG and faithfulness
  20. Practice · 19Google Cloud choices: Cloud SQL, AlloyDB, Vector Search, Agent Retrieval, RAG Engine, Agent Search
  21. Practice · 20Other ecosystems: libraries, engines and managed services
  22. Practice · 21Operations: migrations, deletes, permissions and freshness
  23. Practice · 22Advanced retrieval: rewriting, hierarchies, late interaction, graphs, agents
  24. Practice · 23Reference architectures: local-first, dual-corpus, managed, Postgres-native
  25. Practice · 24Framework recipes and the decision guide
  26. ReferenceGlossary
  27. AboutAbout this site and its sources
Practice · 19

Google Cloud choices: Cloud SQL, AlloyDB, Vector Search, Agent Retrieval, RAG Engine, Agent Search

Separate products with separate jobs, described from their documentation read on one date: what each stores, how it filters and updates, and what you give up with each.

What you will understand
Google Cloud offers several separate products that touch vectors: two databases, an index service, a search engine with storage, a retrieval pipeline and a search application. None of them is "the Vertex vector database".
What you can do
Place the insurance agent's three corpora on a product by size, filters, update rate, locality, compliance and team skills, and say what each choice gives up.
What you can trust
Every product statement was read in Google's documentation on 2026-11-18. Where the pages read do not say something, this page says so. No prices, no ranking.

The insurer's platform team runs on Google Cloud. The underwriting agent now needs its three corpora in production: the guidance passages of the policy fixture UW-GUIDE, Corpus A with past applicant profiles, and Corpus B with underwriter precedents. In a planning meeting someone writes one line on the whiteboard: "Put it in the Vertex vector DB."

Three engineers read the documentation that afternoon. They come back with six names: Cloud SQL, AlloyDB, Vector Search, Agent Retrieval, RAG Engine and Agent Search, plus an embeddings API. Most pages no longer say "Vertex AI".

The real risk is not the names. Case UW-R03 on this site is a guidance search that returns the superseded 2025.4 roof rule (30 years) because no one filtered on policy_version = '2026.2'. Case UW-R07 is a precedent from another tenant that leaks because the tenant filter ran after the top k rows were chosen. Each product filters, updates and places data differently. The wrong choice does not fail loudly. It returns plausible rows for the wrong version or the wrong book of business.

This page takes the products apart one at a time, from their documentation read on 2026-11-18, then walks the insurance agent through a choice.

What this is not. This page does not decide what enters the model's context window or in what order; that is context.sammuthu.com. It also does not grade the agent's answers; that is eval.sammuthu.com.

Retrieval in one sentence, then the products#

Every page of this site keeps one primitive true. An embedding column holds one vector per row, a list of numbers that places the row's text in a space of meaning. A vector query compares the query's vector with the rows' vectors, ranks the rows by distance and returns the nearest k. The model reads only what retrieval returned. Retrieval is a query. The model reads only what it returns.

Each Google Cloud product below does some part of that sentence for you. The useful question is not "which one is the vector database" but "which part of the sentence does this product own, and which part stays mine".

Before AI. Search had the same layering before language models. PostgreSQL full-text search lived inside the database; Lucene was a library you embedded; a search engine server stored documents and answered queries; a hosted site-search product took your pages and returned a search box. All four "did search". They differed in who stored the data, built the index and decided the ranking.

Google Cloud's retrieval products line up the same way:

LayerWhat the product ownsProduct (as documented on 2026-11-18)
Database with a vector columnYour rows, transactions, joins, plus vector searchCloud SQL for PostgreSQL with pgvector; AlloyDB for PostgreSQL
Index serviceAn approximate index over vectors you send itVector Search
Search engine with storageJSON objects, their vectors, several search typesAgent Retrieval (formerly Vector Search 2.0)
Retrieval pipelineIngestion, chunking, embedding, indexing, retrievalRAG Engine
Search applicationData stores, ranking, generative answersAgent Search
Model endpointTurns text into vectorsThe text embeddings API

Diagram: Six Google Cloud products, read left to right as "the product takes over more of the work"

Each lane is a separate product with its own documentation, filters, updates and regions. On the left you own chunking, embedding and the query; on the right the product owns more and shows you less. Click a box for what it stores and what you give up.

  1. Database with vectors
    1. Cloud SQL + pgvector: Managed PostgreSQL; pgvector 0.8.5 on PostgreSQL 13 and later, as documented on 2026-11-18.
    2. AlloyDB: Managed PostgreSQL-compatible database; documents pre-, post- and inline filtering, inline with ScaNN only.
  2. Index service
    1. Vector Search: Stores ids, vectors and restrict tokens, not your passage text; batch or streaming updates.
  3. Search engine with storage
    1. Agent Retrieval: Collections of JSON Data Objects with named vectors; vector, text, semantic and hybrid search.
  4. Retrieval pipeline
    1. RAG Engine: Builds a corpus and runs the pipeline; several regions need an allowlist for new projects.
  5. Search application
    1. Agent Search: Data stores in, search with its own ranking and generative answers out.

On the left of the diagram you own the chunking, the embedding call, the SQL and the filters, and you see every step. On the right the product chunks, embeds and ranks for you, and you see less. Neither end is better; what matters is which steps the insurance agent must be able to audit.

Common confusion. The release notes entry of April 22, 2026 says Vertex AI "is now part of Gemini Enterprise Agent Platform". It says "part of", not "renamed". The same entry maps old names to new ones: Vertex AI Vector Search to Vector Search, Vertex AI Vector Search 2.0 to Agent Retrieval, Vertex AI RAG Engine to RAG Engine, Vertex AI Search to Agent Search. The Agent Search page says Vertex AI Search "is being renamed", and the console still calls it AI Applications. IAM role ids keep the aiplatform prefix: roles/aiplatform.user now displays as "Agent Platform User".

The smallest primitive: what each product asks you to send#

The quickest way to see the difference between the layers is to look at what a query looks like in each. The four shapes below are documented shapes, assembled from the pages read on 2026-11-18; they were not run here. The SQL uses a bound parameter $1 for the query vector and $2, $3 for the filters, never a string pasted into the query.

On Cloud SQL or AlloyDB, retrieval is SQL. The filter and the vector ranking sit in one statement, next to the rest of the row:

-- documented shape; not run here (pgvector operators as in its README)
SELECT passage_id, rule_id, policy_version, embedding <=> $1 AS cosine_distance
FROM guidance_passages
WHERE policy_version = $2 AND tenant = $3
ORDER BY embedding <=> $1
LIMIT 50;

On AlloyDB you may also build its ScaNN index. ScaNN is Google's approximate nearest-neighbor algorithm; AlloyDB packages it as the alloydb_scann extension:

-- documented shape; not run here (AlloyDB create-scann-index page)
CREATE EXTENSION IF NOT EXISTS alloydb_scann CASCADE;
CREATE INDEX guidance_scann ON guidance_passages USING scann (embedding cosine);

On Vector Search, there is no SQL and no row. You send a vector and filter tokens called restricts. A namespace is a field name; allow lists the tokens a result must carry:

{"restricts": [
  {"namespace": "policy_version", "allow": ["2026.2"]},
  {"namespace": "tenant", "allow": ["book-east"]}
]}

On Agent Retrieval, the filter is a JSON object keyed by field name. The search page's example uses $eq:

{"policy_version": {"$eq": "2026.2"}}

Notice what moved. In SQL, policy_version is a column you can also join, group and audit. In Vector Search it is a token attached to a vector; the passage text and the rest of the row live somewhere else, and your code joins them back by id. In Agent Retrieval it is a field of a stored JSON object. Three products, three places where the same fact about a guidance passage lives. (book-east is an illustrative tenant value.)

Each product, read on 2026-11-18#

Each section asks the same questions, from storage to what you give up. Where the pages read do not answer, it says "the documentation read here does not say".

Cloud SQL for PostgreSQL with pgvector#

Cloud SQL is "a fully managed relational database service" for PostgreSQL, among others. Google handles backups, failover, patching and monitoring. pgvector is the PostgreSQL extension that adds the vector type and the distance operators; its full story is on pgvector.

QuestionAs documented on 2026-11-18
StoresYour tables, with a vector column in the same row
VersionPostgreSQL 13 and later support pgvector 0.8.5; the upstream latest release is 0.8.7 (2026-10-01)
Data in and updatesSQL INSERT, UPDATE, DELETE in transactions; the extension is created by a cloudsqlsuperuser member on the primary and replicates to read replicas
Embeddings in the databasegoogle_ml_integration provides an embedding() function for Google models, in regions with generative AI model support
FilteringOrdinary WHERE; with an approximate index pgvector applies the filter after the index scan, and iterative scans (0.8.0 and later) keep scanning
HybridYou write it: the pgvector README suggests PostgreSQL full-text search plus Reciprocal Rank Fusion or a cross-encoder
NetworkingPrivate IP through private services access (VPC Network Peering)
BackupAutomated and on-demand backups; point-in-time recovery; retention from 1 day to 10 years
You give upNothing proprietary in the query: it is PostgreSQL and pgvector. You run index tuning and extension upgrades yourself
Production pitfall. Cloud SQL maintenance installs new extension binaries but does not update the extension in the database catalog. Someone must run ALTER EXTENSION vector UPDATE; until then the database may run an older version than the binaries.

AlloyDB for PostgreSQL#

AlloyDB is described as "a fully managed, PostgreSQL-compatible database service". For vectors it lists two extensions: vector 0.8.5.google-1, which is pgvector customized for AlloyDB, and alloydb_scann 0.1.3.

QuestionAs documented on 2026-11-18
StoresYour tables, with vector columns, as in PostgreSQL
Indexespgvector's indexes, and a ScaNN index with distance l2, dot_product or cosine, queried with <->, <#>, <=>
Index tuningAutomatic mode (default) or manual mode with num_leaves and a quantizer (SQ8 default, AH in Preview, FLAT); auto_maintenance on by default for auto-tuned indexes
FilteringPre-filtering, post-filtering and inline filtering; the query optimizer picks by estimated cost; inline filtering works with ScaNN only
Embeddings in the databaseembedding() and google_ml.embedding(), the second with task types and registered third-party models
NetworkingPrivate services access
BackupContinuous backup on by default (14-day default window, 1 to 35 days), point-in-time recovery, plus on-demand and automated backups
You give upA ScaNN index and the google_ml functions exist only on AlloyDB; plain pgvector SQL stays portable

Inline filtering, as AlloyDB documents it, uses the vector index and a secondary index such as a btree together, so the tenant condition limits which rows are scored instead of trimming a top-k list afterwards. That is the behavior case UW-R07 needs. AlloyDB also says ScaNN can build faster, use less memory and serve more queries than HNSW "depending on workload": a vendor statement, not a measurement on your data.

Vector Search is "a vector search engine from Google Research", built on ScaNN. It is an index you deploy, not a table you query. The Agent Retrieval overview calls it "ANN index as a service".

QuestionAs documented on 2026-11-18
StoresVectors with ids, restrict tokens, numeric restricts and a crowding tag; not your passage text
IndextreeAhConfig (approximate, dense only) or bruteForceConfig (linear search); dimensions required for dense vectors
DistanceDOT_PRODUCT_DISTANCE (default), SQUARED_L2_DISTANCE, L1_DISTANCE, COSINE_DISTANCE; the docs suggest dot product with UNIT_L2_NORM instead of cosine
Data in and updatesBatch: UpdateIndex with a contentsDeltaUri. Streaming: upsertDatapoints, removeDatapoints on a deployed index, visible "after a short delay". A batch index cannot be converted to streaming
FilteringToken restricts (allow, deny; AND across namespaces, OR within one) and numeric restricts (LESS, LESS_EQUAL, EQUAL, GREATER_EQUAL, GREATER)
HybridDense and sparse vectors in one index, fused with RRF; rrf_ranking_alpha 1 = dense only, 0 = sparse only
NetworkingPublic endpoints with OAuth, or private endpoints; Private Service Connect for internal IP addresses
LimitsPer project per region: 100 indexes, 50 deployed index nodes, 6,000 streaming update requests per minute, among others; maximum dimension: the documentation read here does not say
BackupThe documentation read here does not say
You give upYour text and metadata live in another store; your code joins results back by id and keeps the two in step

Two details change the design. Deployment defaults to two replicas and typically takes 20 to 30 minutes: an index is infrastructure with a lifecycle. And the filtering page says restricts tell Vector Search which vectors to ignore without saying whether that happens during the approximate search; test a selective tenant filter before relying on it for UW-R07.

Agent Retrieval (formerly Vector Search 2.0)#

Agent Retrieval is described as "a fully managed, self-tuning search engine" that stores data and retrieves it. Its unit is a Collection of Data Objects, JSON objects with a schema, rather than an index. The overview read here shows no overall Preview or GA label.

QuestionAs documented on 2026-11-18
StoresJSON Data Objects with data fields and named vectors, dense or sparse
Data in and updatesCreate, update and delete one object or up to 1,000 per batch request; import from Cloud Storage (JSONL, AVRO and two legacy Vector Search formats) as a long-running operation
FreshnessThe data-objects page does not say when a write becomes searchable
EmbeddingsAuto-embeddings from built-in models, or your own vectors
Search typesVector search, text search, semantic search (auto-embedded fields only), and hybrid
FilteringJSON filters keyed by field name, e.g. $eq; whether filters run inside the approximate search, the search page does not say
HybridbatchSearch runs several searches in parallel and merges them with RRF; an optional ranker can rerank
Networking and regionVPC Service Controls supported; nine regions listed, including us-central1, us-east4, europe-west4
Backup, quotasThe documentation read here does not say
You give upA proprietary object model and API (google.cloud.vectorsearch_v1); auto-embedding ties the vectors to Google's built-in model

RAG Engine#

RAG Engine is "a component of Gemini Enterprise Agent Platform for retrieval-augmented generation". It builds an index it calls a corpus, and runs the whole pipeline: ingestion, chunking, embedding, indexing, retrieval and generation.

QuestionAs documented on 2026-11-18
StoresBy default RagManagedDb, which the overview says is a Spanner instance; alternatives are Vector Search, Feature Store (Preview), Weaviate (Preview) and Pinecone
Data in and updatesImport files from other storage (ragFiles/import), upload local files, delete a file (ragFiles/delete); "concurrent operations on corpora aren't supported"
Chunking and embeddingDone by the engine; the quickstart's chunk_size=512, chunk_overlap=100 and text-embedding-005 are example values, not stated defaults
Filtering, hybridThe overview and corpus-management pages read here do not mention metadata filtering or hybrid search
RerankingThe ranking API (example semantic-ranker-default@latest) or an LLM reranker with Gemini models
SecurityVPC-SC and CMEK supported; data residency and AXT security controls listed as not supported
Regionus-central1, us-east4, us-east1 and europe-west1 need an allowlist for new projects; europe-west3 and europe-west4 are GA without one; many others are Preview
You give upChunking and embedding decisions move into the service; you manage lifecycle and scaling for every vector store except RagManagedDb

Agent Search (Vertex AI Search, being renamed)#

Agent Search is for building "enterprise generative AI search and recommendation apps", usable with limited machine-learning skills. It is an application layer: you give it data stores, it gives you search with its own ranking, generative answers and summaries. It uses the Discovery Engine API.

QuestionAs documented on 2026-11-18
StoresData stores: search, custom recommendations (Preview), media, healthcare FHIR
FilteringA filter string over indexable fields, with ANY, comparisons, AND, OR, NOT; only certain fields support filtering
RankingIts own ranking, tuning and self-learning ranking from user events
Regionglobal (recommended unless compliance requires otherwise), or the us and eu multi-regions with at-rest data residency
Multi-region limitsIn us and eu, user events do not affect results and results may differ from the global API
Hybrid, updates, private networking, backupThe documentation read here does not say
You give upThe most control: Google decides chunking, ranking and answer generation; you configure, you do not see the query

The ranking API that RAG Engine can call reranks up to 1,000 records per request and returns a 0-to-1 relevance score per record, with no index. A 0-to-1 score is still not a probability; see reranking.

The text embeddings API#

Every product above needs vectors from somewhere. The embeddings API is a model endpoint, not a store. Its models, task types and truncation default are in the folded block "The embeddings API" below; two of those settings cause the failures described later on this page.

The matrix, conditioned on your project#

The lab marks each product as fits, does not fit or unknown for the conditions you tick. Unknown means the pages read on 2026-11-18 did not say, never that the feature is missing. The table under it holds the same information for a reader without JavaScript; every cell comes from the sections above.

OptionWhat it isStores vectors whereFilteringHybridUpdatesNetworking and regionSource
Cloud SQL for PostgreSQL with pgvectorManaged PostgreSQL; pgvector 0.8.5 on PostgreSQL 13+A vector column in your own rowsSQL WHERE; filter after an approximate index scan; iterative scansYou write it: full-text search plus RRF in SQLINSERT, UPDATE, DELETE in transactions; embedding() in SQL; no chunking step describedPrivate IP via private services accessdocs
AlloyDB for PostgreSQLManaged PostgreSQL-compatible database; pgvector plus ScaNN indexA vector column in your own rowsPre-, post- and inline filtering (inline with ScaNN only)You write it: PostgreSQL full-text plus pgvectorSQL writes; ScaNN auto_maintenance on by default; no chunking step describedPrivate services accessdocs
Vector SearchApproximate index as a service, built on ScaNNA deployed index; text and metadata elsewhereToken and numeric restricts; timing during search not statedDense plus sparse in one index, RRFBatch updates, or streaming upserts on a streaming indexPublic with OAuth, private endpoint, Private Service Connectdocs
Agent Retrieval (formerly Vector Search 2.0)Managed search engine that stores JSON objects; no overall launch stage shownCollections of Data Objects with named vectorsJSON filters such as $eqbatchSearch merged with RRFCreate, update, delete, batch of 1,000, Cloud Storage import; freshness not statedVPC Service Controls; nine listed regionsdocs
RAG EngineManaged retrieval pipeline: ingest, chunk, embed, index, retrieveRagManagedDb (Spanner) by default, or another listed storeNot mentioned on the pages readNot mentioned on the pages readImport, upload, delete files; no concurrent corpus operationsVPC-SC, CMEK; several regions need an allowlistdocs
Agent SearchSearch and recommendation application with its own rankingData stores managed by the productfilter string over certain indexable fieldsNot stated on the pages readNot stated on the pages readglobal, or us and eu multi-regions with data residencydocs

The PostgreSQL rows show more "fits" because their conditions are well documented and this table favors relational needs, not because they suit every team; untick postgres-skills and sql-joins and the picture changes. The unknowns on the other rows are a finding too: test freshness, filter timing and backup before you commit.

Walking the insurance agent through the choice#

Now take the insurer's three corpora through the six conditions.

Size. Corpus B in this site's case UW-R10 grows from 40 to 4,000 precedents (illustrative). Growth changes whether an index is worth building, not where the rows must live, and no size by itself picks a product. The scale page shows how to measure instead of guessing.

Filters. Every corpus filters on exact metadata: policy_version and status for guidance, wind_zone and tenant for Corpus A, policy_version, override and tenant for Corpus B. The tenant filter is a permission, so "does the filter run inside the search" comes first. AlloyDB documents inline filtering with ScaNN; pgvector documents filtering after the index scan plus iterative scans; Vector Search and Agent Retrieval document filters but not their timing; RAG Engine's pages read here do not mention metadata filtering, which keeps it off Corpus B until tested.

Update rate. Guidance changes when a policy version ships. Precedents arrive with every decision. Same-day search favors transactional writes (Cloud SQL, AlloyDB) or a streaming index (Vector Search, fixed at creation).

Locality and compliance. Check the region list first. RAG Engine needs an allowlist in four regions for new projects and lists data residency as not supported. Agent Search offers at-rest data residency only in its us and eu multi-regions.

Team skills. A team that already runs PostgreSQL and reads EXPLAIN output keeps those skills with Cloud SQL or AlloyDB. A team without database operations gains from a product that owns the index and the scaling, and pays with less visibility.

Diagram: Placing the insurer's three corpora: conditions first, product last

Read the questions in order. Each one removes options for a stated reason from the documentation read on 2026-11-18. The last lane is one defensible design for these conditions, not a recommendation for every project.

  1. 1 · Filters
    1. Tenant and version filters: Every corpus filters on exact metadata; the tenant filter is a permission (UW-R07).
  2. 2 · Updates
    1. Same-day precedents: A precedent decided today must be retrievable today; a batch index cannot become streaming.
  3. 3 · Region and compliance
    1. Region list: Check the product's region table first; some regions need an allowlist.
  4. 4 · Team skills
    1. Runs PostgreSQL today?: A team that already runs PostgreSQL keeps its skills; a team without operations gains from a managed index.
  5. 5 · One design
    1. Three tables, one database: Exact filters, same-day writes and joins back to source rows, for these conditions only.

Put together, one defensible design for this insurer keeps all three corpora as tables in one PostgreSQL database, Cloud SQL or AlloyDB: every corpus needs exact filters, precedents need same-day writes, and the audit trail needs joins back to source rows. Agent Search could serve a separate, human-facing search over policy documents. That is a design for these conditions, not a recommendation for yours.

In the insurance build. In that build, both corpora live in PostgreSQL 16 with pgvector, run from the pgvector/pgvector:pg16 docker image, not on a managed Google Cloud product. Corpus A uses an HNSW index with hnsw.iterative_scan = relaxed_order when pgvector is 0.8 or later; Corpus B has no ANN index and sorts the few filtered rows exactly. Cloud SQL's listed pgvector 0.8.5 meets that 0.8 condition, so the same SQL shape would apply there; nothing on this page was run on Cloud SQL.

What goes wrong when the products are treated as one#

The whiteboard line "Put it in the Vertex vector DB" hides three failures. Each one returns rows that look right.

The first is a filter that lives in the wrong place. Suppose the team puts guidance vectors in Vector Search and keeps policy_version only in the passage table. The query asks for the 50 nearest passages, then the application drops the 2025.4 ones. If most of the 50 were old roof passages, few or none survive, and case UW-R03 comes back: the agent cites a superseded rule or cites nothing. The fix is to send policy_version as a restrict with the vector, and to test it with a query whose nearest neighbors are mostly superseded.

The second is a silent truncation. The embeddings API truncates over-long input by default. A guidance chunk that carries the full text of R-ROOF-03 plus a long preamble may lose its end, which is the part that names the roof limit. Nothing errors. The vector describes the preamble. Set autoTruncate to false so the ingestion job fails loudly, and fix the chunking (see chunking).

The third is a mismatch of models or task types. A query embedded with a different model of the same dimension lands in a different space; that is this site's case UW-R06, where results look plausible and are wrong. A query sent without the RETRIEVAL_QUERY task type departs from the documented guidance in a quieter way. Store the model name and task type next to every vector and refuse a query that does not match (see embeddings).

In a coding agent. A coding agent on Google Cloud faces the same layering for a repository. A table of code chunks with a vector column and a path column keeps exact filters ("only src/billing/") in SQL next to the vector search. A managed search application over the repository returns good passages but does not show why. Grep and symbol lookup stay lexical either way; the semantic query "where do we retry provider calls" is the only part that needs vectors.

A checklist for Monday#

QuestionWhy it matters
Which part of the retrieval sentence does this product own: storage, index, embedding, chunking, ranking?Everything it owns is something you cannot inspect line by line
Can tenant and policy_version filter inside the search, and is that documented or tested?A filter after top-k leaks (UW-R07) or starves (UW-R03)
Where do the passage text and metadata live, and who keeps them in step with the vectors?An index service stores ids and vectors, not your rows
When is a new precedent searchable, and is that stated or measured?Same-day decisions need same-day retrieval
Is the region on the product's list, without an allowlist?Some products need an allowlist in common regions
Are the embedding model, task type and autoTruncate setting pinned and stored with each vector?Defaults change ranking silently
Which IAM role ids and package names does your code use?Display names changed; role ids kept aiplatform
What did you read, and on what date?This page was read on 2026-11-18; names and stages are still moving
The embeddings APIModels, task types, truncation and normalization, as documented on 2026-11-18

The text embeddings page lists gemini-embedding-001 (up to 3072 dimensions, 2048 tokens), gemini-embedding-2 (up to 3072 dimensions, 8192 tokens; generally available on April 22, 2026, per the release notes), text-embedding-005 (up to 768) and text-multilingual-embedding-002 (up to 768). output_dimensionality shrinks the output; the default is full length.

Task types tell the model what a text is for. The guidance is to embed the corpus with RETRIEVAL_DOCUMENT and queries with RETRIEVAL_QUERY, and not to use SEMANTIC_SIMILARITY for retrieval. The task-types page lists three supported models and does not list gemini-embedding-2, so check before you assume a task type applies to it.

autoTruncate defaults to true: an over-long input is cut silently. Set it to false so over-limit input fails. The page says returned vectors are normalized, so cosine, dot product and Euclidean distance rank the same; it does not say whether that still holds after output_dimensionality shrinks a vector. If you shorten vectors, normalize them yourself before storing.

The page is also internally inconsistent on batch size: it gives up to 250 input texts per request, while its REST section says gemini-embedding-001 accepts one input text per request. Write the ingestion job so that a batch-size error retries with smaller batches instead of dropping texts.

Lock-in, measured as the cost of leavingWhat each product's data looks like on the way out

Lock-in is easier to reason about as an exit plan than as a feeling. Ask, for each product: if we leave next year, what do we export, in which format, and what must we recompute?

Cloud SQL and AlloyDB keep the corpus as PostgreSQL rows. The vectors, the text and the metadata leave together in a dump and load into any PostgreSQL with pgvector. What does not leave is AlloyDB's ScaNN index and its google_ml functions; you rebuild an HNSW or IVFFlat index elsewhere and move embedding calls into application code. That is a reindex, not a re-embedding, because the vectors are unchanged.

Vector Search stores only ids, vectors and restricts. Leaving means exporting vectors and rebuilding the restricts from your own tables, which you already had to keep in step. The embedding model is yours, so the vectors stay valid.

Agent Retrieval imports JSONL and AVRO and accepts two legacy Vector Search formats, which suggests a migration path into it. If you use its auto-embeddings, the vectors come from Google's built-in model; leaving means re-embedding the whole corpus with a model you control, and re-labeling your evaluation set against the new space.

RAG Engine and Agent Search hold the most decisions: chunk boundaries, embedding model, ranking. Leaving means rebuilding the pipeline and re-establishing the retrieval quality you had, measured on your own labeled queries. Keep the source documents and your golden set outside the product from day one, because they are the only parts that make the exit measurable.

Filtering semantics differ more than the word "filter" suggestsTokens, JSON operators, SQL, and where tenancy belongs

Vector Search restricts are tokens in namespaces. Within one namespace the tokens are ORed; across namespaces they are ANDed; deny tokens exclude. Numeric restricts compare one number type per namespace and do not list NOT_EQUAL. So "policy_version is 2026.2 and tenant is book-east and status is not superseded" must be expressed as allow tokens, or as a deny token on superseded. The overview warns that many restricts increase memory use and shard count, so a restrict per user id is a design to test, not a default.

Agent Retrieval's search page shows only $eq in the parts read. Agent Search filters work only on certain key properties, and the docs warn that being indexable does not guarantee a field can be filtered. In SQL, any column and any expression can filter, and AlloyDB's optimizer can pick pre-, post- or inline filtering per query and show the choice in the plan's Execution Strategy field.

For tenancy, the stronger designs do not rely on a filter at all. Separate tables or separate indexes per tenant remove the leak by construction, at the price of more objects to operate. Where a filter must do the job, write a test that queries tenant A with a vector copied from tenant B's row and asserts zero rows from B. The operations page covers tenant isolation in depth.

Naming drift is an operations problemRedirects, 404s, role ids and package names after the April 2026 change

The April 22, 2026 change moved documentation paths. Many old vertex-ai URLs redirect to gemini-enterprise-agent-platform paths, but some return 404 at the old location, including the old Vector Search quotas and networking pages and a RAG Engine page. Runbooks and architecture documents that link to the old paths now break in places.

Code changes more slowly than names. The IAM role ids keep the aiplatform prefix while their display names say "Agent Platform"; a policy written against role ids keeps working, and a review that searches by display name misses roles. The PyPI package is still google-cloud-aiplatform, while the RAG Engine quickstart imports a module named agentplatform; a PyPI page for that name did not render when checked. Cloud SQL's embeddings page still says "Vertex AI" while AlloyDB's says "Agent Platform".

None of this changes how retrieval works. It changes how quickly a new engineer finds the right page. Record the URL and date of every product fact your design depends on, as this site does, and re-read them before a release.

Batch, streaming and transactional updatesThree freshness models and what each costs you in design

A transactional store makes a new precedent visible to the next query after commit, and a delete removes it in the same transaction that removes the source row. This is the simplest model to reason about for permissions: there is no window in which a deleted precedent is still retrievable.

Vector Search offers two models fixed at index creation. A batch index applies a delta file through UpdateIndex; a streaming index accepts upsertDatapoints and removeDatapoints and shows changes after a short delay the documentation does not quantify. Compaction runs automatically, for streaming indexes when the oldest uncompacted data is five days old. Restricts can be updated without re-embedding by setting update_mask to all_restricts, which matters when a precedent changes status from active to revoked.

When the vectors live in one store and the rows in another, a delete is two writes. If the second fails, the index can return an id whose row is gone or, worse, an id whose row was revoked for a reason. Design the reader to tolerate a missing row and to re-check status against the source table after retrieval, and run a reconciliation job that compares ids in both stores.

In one breath#

Google Cloud does not have one vector database. It has two PostgreSQL databases that hold vectors next to your rows, an index service, a search engine that stores JSON objects, a retrieval pipeline and a search application, each with its own filtering, update model and region list, all read here on 2026-11-18. Choose by the work you must be able to inspect: filters inside the search, same-day updates, region and compliance, and the skills your team already has.

The insurance agent now has a place to put its three corpora and a list of what that place does not tell you. The next question is wider: outside Google Cloud there are libraries, extensions, engines and managed services, and comparison charts that try to summarize them with checkmarks. Other ecosystems shows how to read those charts and what they leave out.