Note: This feature is available with the Spanner Enterprise edition and Enterprise Plus edition. For more information, see theSpanner editions overview.

This page describes how to use vector search in Spanner Graphto find K-nearest neighbors (KNN) and approximate nearest neighbors (ANN). Youcan use vector distance functions to perform KNN and ANN vector search for usecases like similarity search or retrieval-augmented generation for generative AIapplications.

Spanner Graph supports the following distance functions toperform KNN vector similarity search:

• COSINE_DISTANCE():measures the shortest distance between two vectors.
• EUCLIDEAN_DISTANCE():measures the cosine of the angle between two vectors.
• DOT_PRODUCT():calculates the cosine of the angle multiplied by the product of correspondingvector magnitudes. If you know that all the vector embeddings in your datasetare normalized, then you can useDOT_PRODUCT() as a distance function.

For more information, seePerform vector similarity search in Spanner by finding the K-nearestneighbors.

Spanner Graph also supports the following approximate distancefunctions toperform ANN vector similarity search:

• APPROX_COSINE_DISTANCE:measures the approximate shortest distance between two vectors.
• APPROX_EUCLIDEAN_DISTANCE:measures the approximate cosine of the angle between two vectors.
• APPROX_DOT_PRODUCT:calculates the approximate cosine of the angle multiplied by the product ofcorresponding vector magnitudes. If you know that all the vector embeddings inyour dataset are normalized, then you can useDOT_PRODUCT() as a distancefunction.

For more information, seeFind approximate nearest neighbors, create vector index, and query vectorembeddings.

Before you begin

To run the examples in this document, you must first follow the steps inSet up and query Spanner Graph to do thefollowing:

1. Create an instance.
2. Create a database with a Spanner Graph schema.
3. Insert essential graph data.

After you insert the essential graph data, make the following updates to yourdatabase.

Insert additional vector data in graph database

To make the required updates to your graph database, do the following:

1. Add a new column,nick_name_embeddings, to theAccount input table.

   ALTERTABLEAccountADDCOLUMNnick_name_embeddingsARRAY<FLOAT32>(vector_length=>4);

2. Add data to thenick_name column.

   UPDATEAccountSETnick_name="Fund for a refreshing tropical vacation"WHEREid=7;UPDATEAccountSETnick_name="Fund for a rainy day!"WHEREid=16;UPDATEAccountSETnick_name="Saving up for travel"WHEREid=20;

3. Create embeddings for the text in thenick_name column, andpopulate them into the newnick_name_embeddings column.

   To generate Vertex AI embeddings for your operational data inSpanner Graph, seeGet Vertex AI text embeddings.

   For illustrative purposes, our examples use artificial, low-dimensionalvector values.

   UPDATEAccountSETnick_name_embeddings=ARRAY<FLOAT32>[0.3,0.5,0.8,0.7]WHEREid=7;UPDATEAccountSETnick_name_embeddings=ARRAY<FLOAT32>[0.4,0.9,0.7,0.1]WHEREid=16;UPDATEAccountSETnick_name_embeddings=ARRAY<FLOAT32>[0.2,0.5,0.6,0.6]WHEREid=20;

4. Add two new columns to theAccountTransferAccount input table:notes andnotes_embeddings.

   ALTERTABLEAccountTransferAccountADDCOLUMNnotesSTRING(MAX);ALTERTABLEAccountTransferAccountADDCOLUMNnotes_embeddingsARRAY<FLOAT32>(vector_length=>4);

5. Create embeddings for the text in thenotes column, and populate them intothenotes_embeddings column.

   To generate Vertex AI embeddings for your operational data inSpanner Graph, seeGet Vertex AI text embeddings.

   For illustrative purposes, our examples use artificial, low-dimensionalvector values.

   UPDATEAccountTransferAccountSETnotes="for shared cost of dinner",notes_embeddings=ARRAY<FLOAT32>[0.3,0.5,0.8,0.7]WHEREid=16ANDto_id=20;UPDATEAccountTransferAccountSETnotes="fees for tuition",notes_embeddings=ARRAY<FLOAT32>[0.1,0.9,0.1,0.7]WHEREid=20ANDto_id=7;UPDATEAccountTransferAccountSETnotes='loved the lunch',notes_embeddings=ARRAY<FLOAT32>[0.4,0.5,0.7,0.9]WHEREid=20ANDto_id=16;

6. After adding new columns to theAccount andAccountTransferAccount inputtables, update the property graph definition using the following statements.For more information, seeUpdate existing node or edge definitions.

   CREATEORREPLACEPROPERTYGRAPHFinGraphNODETABLES(Account,Person)EDGETABLES(PersonOwnAccountSOURCEKEY(id)REFERENCESPerson(id)DESTINATIONKEY(account_id)REFERENCESAccount(id)LABELOwns,AccountTransferAccountSOURCEKEY(id)REFERENCESAccount(id)DESTINATIONKEY(to_id)REFERENCESAccount(id)LABELTransfers);

Find K-nearest neighbors

In the following example, use theEUCLIDEAN_DISTANCE() function to perform KNNvector search on the nodes and edges of your graph database.

Perform KNN vector search on graph nodes

You can perform a KNN vector search on thenick_name_embeddings property oftheAccount node. This KNN vector search returns the account owner'snameand the account'snick_name. In the following example, the result shows thetop two K-nearest neighbors foraccounts for leisure travel and vacation,which is represented by the[0.2, 0.4, 0.9, 0.6] vector embedding.

GRAPHFinGraphMATCH(p:Person)-[:Owns]->(a:Account)RETURNp.name,a.nick_nameORDERBYEUCLIDEAN_DISTANCE(a.nick_name_embeddings,-- An illustrative embedding for 'accounts for leisure travel and vacation'ARRAY<FLOAT32>[0.2,0.4,0.9,0.6])LIMIT2;

Results

Perform KNN vector search on graph edges

You can perform a KNN vector search on thenotes_embeddings property of theOwns edge. This KNN vector search returns the account owner'sname and thetransfer'snotes. In the following example, the result shows the top twoK-nearest neighbors forfood expenses, which is represented by the[0.2, 0.4, 0.9, 0.6] vector embedding.

GRAPHFinGraphMATCH(p:Person)-[:Owns]->(:Account)-[t:Transfers]->(:Account)WHEREt.notes_embeddingsISNOTNULLRETURNp.name,t.notesORDERBYEUCLIDEAN_DISTANCE(t.notes_embeddings,-- An illustrative vector embedding for 'food expenses'ARRAY<FLOAT32>[0.2,0.4,0.9,0.6])LIMIT2;

Results

Create a vector index and find approximate nearest neighbors

To perform an ANN search, you must create aspecialized vector indexthat Spanner Graph uses to accelerate the vector search. The vectorindex must use a specific distance metric. You can choose the distance metricmost appropriate for your use case by setting thedistance_type parameter toone ofCOSINE,DOT_PRODUCT orEUCLIDEAN. For more information, seeVECTOR INDEX statements.

In the following example, you create a vector index using the euclidean distancetype on thenick_name_embedding column of theAccount input table:

CREATEVECTORINDEXNickNameEmbeddingIndexONAccount(nick_name_embeddings)WHEREnick_name_embeddingsISNOTNULLOPTIONS(distance_type='EUCLIDEAN',tree_depth=2,num_leaves=1000);

Perform ANN vector search on graph nodes

After you create a vector index, you can perform a ANN vector search on thenick_name property of theAccount node. The ANN vector search returns theaccount owner'sname and the account'snick_name. In the following example,the result shows the top two approximate nearest neighbors foraccounts forleisure travel and vacation, which is represented by the[0.2, 0.4, 0.9, 0.6] vector embedding.

Thegraph hintforces the query optimizer to use the specified, vector index in the queryexecution plan.

GRAPHFinGraphMATCH(@{FORCE_INDEX=NickNameEmbeddingIndex}a:Account)WHEREa.nick_name_embeddingsISNOTNULLRETURNa,APPROX_EUCLIDEAN_DISTANCE(a.nick_name_embeddings,-- An illustrative embedding for 'accounts for leisure travel and vacation'ARRAY<FLOAT32>[0.2,0.4,0.9,0.6],options=>JSON'{"num_leaves_to_search": 10}')ASdistanceORDERBYdistanceLIMIT2NEXTMATCH(p:Person)-[:Owns]->(a)RETURNp.name,a.nick_name;

Results

What's next

• Perform vector similarity search in Spanner by finding the K-nearest neighbors.
• Find approximate nearest neighbors, create vector index, and query vector embeddings.
• Get Vertex AI text embeddings
• Learn more aboutSpanner Graph queries.
• Learnbest practices for tuning queries.