# Working with vector similarity in Neptune Analytics
You can answer complex questions about your data by transforming data shapes into embeddings (that is, vectors). Using a vector search index lets you answer questions about your data's context and its similarity and connection to other data.
For example, a support agent could translate a question that they receive into a vector and use it to search the support knowledge base for articles that are similar to the words in the question (implicit similarity). For the most applicable articles, they could then collect metadata about the author, previous cases, runbooks, and so on so as to provide additional context when answering the question (explicit data).
Vector similarity search in Neptune Analytics makes it easy for you to build machine learning (ML) augmented search experiences and generative artificial intelligence (GenAI) applications. It also gives you an overall lower total cost of ownership and simpler management overhead because you no longer need to manage separate data stores, build pipelines, or worry about keeping the data stores in sync. You can use vector similarity search in Neptune Analytics to augment your LLMs by integrating graph queries for domain-specific context with the results from low-latency, nearest-neighbor similarity search on embeddings imported from LLMs hosted in Amazon Bedrock, Graph Neural Networks (GNNs) in GraphStorm, or other sources.
As an example, Bioinformatics researchers who are interested in re-purposing existing blood pressure drugs for other treatable diseases, want to use vector similarity search over in-house knowledge graphs to find patterns in protein interaction networks.
For another example, a large online book retailer may need to use known pirated material to quickly identify similar media in conjunction with a knowledge graph to identify patterns of deceptive listing behaviours and find malicious sellers.
In both cases, vector search over a knowledge graph increases accuracy and speed when building the solution. It reduces the operational overhead and complexity using the tools available today.
You can create a vector index for your graph to try out this feature. Neptune Analytics supports associating embeddings generated from LLMs with the nodes of your graphs.
**Contents**
+ [Vector indexing in Neptune Analytics](vector-index.md)
+ [Vector index transaction support](vector-index.md#vector-index-transaction-support)
+ [Loading vectors into a Neptune Analytics graph vector index](vector-index.md#loading-vectors)
+ [Load the vectors from graph data files in Amazon S3](vector-index.md#load-vectors-from-s3)
+ [Using the `vectors.upsert` algorithm to load vectors for your graph](vector-index.md#load-vectors-using-upsert)
+ [Common errors you may encounter when loading embeddings](vector-index.md#load-embedding-errors)
+ [Vector-search algorithms in Neptune Analytics](vector-index.md#vector-algorithms)
+ [Vector-similarity search (VSS) algorithms in Neptune Analytics](vss-algorithms.md)
+ [The `.vectors.distance` algorithm (deprecated)](vectors-distance.md)
+ [`.vectors.distance` syntax](vectors-distance.md#vectors-distance-syntax)
+ [`.vectors.distance` inputs](vectors-distance.md#vectors-distance-inputs)
+ [`.vectors.distance` outputs](vectors-distance.md#vectors-distance-outputs)
+ [`.vectors.distance` query examples](vectors-distance.md#vectors-distance-query-example)
+ [Sample `.vectors.distance` output](vectors-distance.md#vectors-distance-sample-output)
+ [The `.vectors.distance.byNode` algorithm](vectors.distance.byNode.md)
+ [`.vectors.distance.byNode` syntax](vectors.distance.byNode.md#vectors.distance.byNode-syntax)
+ [`.vectors.distance.byNode` inputs](vectors.distance.byNode.md#vectors.distance.byNode-inputs)
+ [`.vectors.distance.byNode` outputs](vectors.distance.byNode.md#vectors.distance.byNode-outputs)
+ [`.vectors.distance.byNode` query examples](vectors.distance.byNode.md#vectors.distance.byNode-query-example)
+ [Sample `.vectors.distance.byNode` output](vectors.distance.byNode.md#vectors.distance.byNode-sample-output)
+ [The `.vectors.distanceByEmbedding` algorithm (deprecated)](vectors-distance-embedding.md)
+ [`.vectors.distanceByEmbedding` syntax](vectors-distance-embedding.md#vectors-distance-embedding-syntax)
+ [`.vectors.distanceByEmbedding` inputs](vectors-distance-embedding.md#vectors-distance-embedding-inputs)
+ [`.vectors.distanceByEmbedding` outputs](vectors-distance-embedding.md#vectors-distance-embedding-outputs)
+ [`.vectors.distanceByEmbedding` query examples](vectors-distance-embedding.md#vectors-distance-embedding-query-example)
+ [Sample `.vectors.distanceByEmbedding` output](vectors-distance-embedding.md#vectors-distance-embedding-sample-output)
+ [The `.vectors.distance.byEmbedding` algorithm](vectors.distance.byEmbedding.md)
+ [`.vectors.distance.byEmbedding` syntax](vectors.distance.byEmbedding.md#vectors.distance.byEmbedding-syntax)
+ [`.vectors.distance.byEmbedding` inputs](vectors.distance.byEmbedding.md#vectors.distance.byEmbedding-inputs)
+ [`.vectors.distance.byEmbedding` outputs](vectors.distance.byEmbedding.md#vectors.distance.byEmbedding-outputs)
+ [`.vectors.distance.byEmbedding` query examples](vectors.distance.byEmbedding.md#vectors.distance.byEmbedding-query-example)
+ [Sample `.vectors.distance.byEmbedding` output](vectors.distance.byEmbedding.md#vectors.distance.byEmbedding-sample-output)
+ [The `.vectors.get` algorithm](vectors-get.md)
+ [`.vectors.get` syntax](vectors-get.md#vectors-get-syntax)
+ [`.vectors.get` input](vectors-get.md#vectors-get-inputs)
+ [`.vectors.get` outputs](vectors-get.md#vectors-get-outputs)
+ [`.vectors.get` query example](vectors-get.md#vectors-get-query-example)
+ [Sample `.vectors.get` output](vectors-get.md#vectors-get-sample-output)
+ [.vectors.topKByEmbedding algorithm (deprecated)](vectors-topKByEmbedding.md)
+ [`.vectors.topKByEmbedding` syntax](vectors-topKByEmbedding.md#vectors-topKByEmbedding-syntax)
+ [`.vectors.topKByEmbedding` input](vectors-topKByEmbedding.md#vectors-topKByEmbedding-inputs)
+ [`.vectors.topKByEmbedding` outputs](vectors-topKByEmbedding.md#vectors-topKByEmbedding-outputs)
+ [`.vectors.topKByEmbedding` query example](vectors-topKByEmbedding.md#vectors-topKByEmbedding-query-example)
+ [Sample `.vectors.topKByEmbedding` output](vectors-topKByEmbedding.md#vectors-topKByEmbedding-sample-output)
+ [.vectors.topK.byEmbedding algorithm](vectors.topK.byEmbedding.md)
+ [`.vectors.topK.byEmbedding` syntax](vectors.topK.byEmbedding.md#vectors.topK.byEmbedding-syntax)
+ [`.vectors.topK.byEmbedding` input](vectors.topK.byEmbedding.md#vectors.topK.byEmbedding-inputs)
+ [`.vectors.topK.byEmbedding` outputs](vectors.topK.byEmbedding.md#vectors.topK.byEmbedding-outputs)
+ [`.vectors.topK.byEmbedding` query example](vectors.topK.byEmbedding.md#vectors.topK.byEmbedding-query-example)
+ [Sample `.vectors.topKByEmbedding` output](vectors.topK.byEmbedding.md#vectors-topKByEmbedding-sample-output)
+ [.vectors.topKByNode algorithm (deprecated)](vectors-topKByNode.md)
+ [`.vectors.topKByNode` syntax](vectors-topKByNode.md#vectors-topKByNode-syntax)
+ [`.vectors.topKByNode` input](vectors-topKByNode.md#vectors-topKByNode-inputs)
+ [`.vectors.topKByNode` outputs](vectors-topKByNode.md#vectors-topKByNode-outputs)
+ [`.vectors.topKByNode` query example](vectors-topKByNode.md#vectors-topKByNode-query-example)
+ [Sample `.vectors.topKByNode` output](vectors-topKByNode.md#vectors-topKByNode-sample-output)
+ [.vectors.topK.byNode algorithm](vectors.topK.byNode.md)
+ [`.vectors.topK.byNode` syntax](vectors.topK.byNode.md#vectors.topK.byNode-syntax)
+ [`.vectors.topK.byNode` input](vectors.topK.byNode.md#vectors.topK.byNode-inputs)
+ [`.vectors.topK.byNode` outputs](vectors.topK.byNode.md#vectors.topK.byNode-outputs)
+ [`.vectors.topK.byNode` query example](vectors.topK.byNode.md#vectors.topK.byNode-query-example)
+ [Sample `.vectors.topK.byNode` output](vectors.topK.byNode.md#vectors.topK.byNode-sample-output)
+ [.vectors.upsert algorithm](vectors-upsert.md)
+ [`.vectors.upsert` syntax](vectors-upsert.md#vectors-upsert-syntax)
+ [`.vectors.upsert` input](vectors-upsert.md#vectors-upsert-inputs)
+ [`.vectors.upsert` outputs](vectors-upsert.md#vectors-upsert-outputs)
+ [`.vectors.upsert` query examples](vectors-upsert.md#vectors-upsert-query-example)
+ [Sample `.vectors.upsert` output](vectors-upsert.md#vectors-upsert-sample-output)
+ [.vectors.remove algorithm](vectors-remove.md)
+ [`.vectors.remove` syntax](vectors-remove.md#vectors-remove-syntax)
+ [`.vectors.remove` input](vectors-remove.md#vectors-remove-inputs)
+ [`.vectors.remove` outputs](vectors-remove.md#vectors-remove-outputs)
+ [`.vectors.remove` query examples](vectors-remove.md#vectors-remove-query-example)
+ [Sample `.vectors.remove` output](vectors-remove.md#vectors-remove-sample-output)
# Vector indexing in Neptune Analytics
You can only create a vector search index for a Neptune Analytics graph at the time the graph is created. Neptune Analytics lets you create only one vector index for a graph, with a fixed dimension between 1 and 65,535 inclusive.
When you [create a Neptune Analytics graph in the console](create-graph-using-console.md), you specify the index dimension under **Vector search settings** near the end of the process.
## Vector index transaction support
When using Neptune Analytics with a vector search index, it is important to understand that any updates performed on the vector index are not ACID compliant — specifically, any updates to the vector index are not atomic in nature. Atomicity in a database defines that when updates are performed, either all or none of them succeed. The changes to vector embeddings (inserts, deletes, and updates), unlike other parts of the graph, are non-atomic and not isolated.
Atomicity ensures that either all or no updates by a query are applied. Isolation ensures that concurrent queries do not see effects of a running query. However, changes to vector embeddings by a query become durable on write and visible to all other queries, even if that query fails later.
If a query updates the vector embeddings and makes other changes to the graph, then only the latter are atomic and isolated. For instance, if you are running a bulk load using a `neptune.load()` request that adds new vertices with vector embeddings and it fails midway, then the graph would contain vertex embeddings for a subset of new vertices that were written before the request failed.
To minimize inconsistencies to vector updates, we recommend the following:
1. Avoid concurrently updating vector embeddings for any vertex.
1. Make queries that update vector embeddings idempotent and retry failed queries. For instance, a failed `neptune.load()` request can be retried to apply the remainder of the vector embedding properties and the rest of the properties for all the vertices in the input dataset. The following two example queries illustrate this. The first one finds vertices by given IDs and upserts their embeddings, and is likely to succeed on retry if the query fails. However, the second query creates vertices with given IDs and embeddings, and retries may not help if the query fails because a vertex already exists with one of the IDs. Thus the second query pattern should be avoided.
**Example: idempotent upsert query**
```
UNWIND [
{id: "933", embedding: [1,2,3,4]},
{id: "934", embedding: [-1,-2,-3,-4]}
] as entry
MATCH (n:person) WHERE id(n)=entry.id WITH n, entry.embedding as embedding
CALL neptune.algo.vectors.upsert(n, embedding)
YIELD success
RETURN n, embedding, success
```
**Example: non-idempotent upsert query (avoid this pattern)**
In this case, if a vertex with ID '934' already exists then the `CREATE` for the second vertex would fail even on retries, but the side effect of embeddings added to the vertex with ID "933" would remain because those embeddings were committed on insert.
```
UNWIND [
{id: "933", embedding: [1,2,3,4]},
{id: "934", embedding: [-1,-2,-3,-4]}
] as entry
CREATE (n:person {`~id`: entry.id}) WITH n, entry.embedding as embedding
CALL neptune.algo.vectors.upsert(n, embedding)
YIELD success
RETURN n, embedding, success
```
1. Use simple queries for updating vectors and avoid chaining vector operations with other vector operations or other vertex/property/edge updates. For instance, the following query updates embeddings for a vertex and creates another vertex. Separating them into two queries should help avoid inconsistencies.
```
MATCH (n {`~id`: '933'}) CALL neptune.algo.vectors.upsert(n, [1,2,3,4])
YIELD success
CREATE (m {`~id`: '934'})
```
## Loading vectors into a Neptune Analytics graph vector index
Note that the nodes in your graph must have at least one user property or label in order to associate them with embeddings. Also, Neptune Analytics does not support the special positive and negative infinity (`INF`, `-INF`) and not-a-number (`NaN`) floating-point values.
Neptune Analytics supports optional embeddings in the CSV file when the vector index is enabled. This means that not every node needs to be associated with an embedding.
Neptune Analytics does not currently support loading vectors from Neptune Database or a snapshot.
There are two ways you can load vectors associated with nodes in your graph:
### Load the vectors from graph data files in Amazon S3
When you're loading graph data from files in Amazon S3 using the console or the [`neptune.load{}`](batch-load.md) openCypher integration, you can add a column to your CSV data with an `embedding:vector` header. This column should contain a list of integer or floating-point values separated by semicolons (` ; `) that forms a vector of the required dimension and is the embedding for the node in question.
For example, associating a 4-dimensional vector with nodes in your graph in the openCypher CSV format would look like this:
```
:ID, name:String, embedding:Vector, :LABEL
v1,"ABC",0.1;0.5;0.8;-1.32,person
v2,"DEF",8.1;-0.2;0.432;-1.02,person
v3,"GHI",12323343;24324;2433554;-4343434,person
v4,"JKL",121.12213;3223.212;265;-1.32,person
```
In the Gremlin CSV format, the same thing would look like this:
```
~id, name, embedding:vector, ~label
v1,"ABC",0.1;0.5;0.8;-1.32,person
v2,"DEF",8.1;-0.2;0.432;-1.02,person
v3,"GHI",12323343;24324;2433554;-4343434,person
v4,"JKL",121.12213;3223.212;265;-1.32,person
```
### Using the `vectors.upsert` algorithm to load vectors for your graph
You can also use the [vectors.upsert](vectors-upsert.md) algorithm to insert or update embeddings in a Neptune Analytics graph that has a vector search index. For example, in openCypher you can call the algorithm like this:
```
CALL neptune.algo.vectors.upsert(
"person933",
[0.1, 0.2, 0.3, ..]
)
YIELD node, embedding, success
RETURN node, embedding, success
```
Another example is:
```
UNWIND [
{id: "933", embedding: [1,2,3,4]},
{id: "934", embedding: [-1,-2,-3,-4]}
] as entry
MATCH (n:person) WHERE id(n)=entry.id WITH n, entry.embedding as embedding
CALL neptune.algo.vectors.upsert(n, embedding)
YIELD success
RETURN n, embedding, success
```
## Common errors you may encounter when loading embeddings
+ If the embeddings you are trying to load have a different dimension than is expected by the vector index, the load fails with parsing exception and a message like the following:
```
An error occurred (ParsingException) when calling the
ExecuteOpenCypherQuery operation: Could not load vector embedding: (the
embedding in question). Please check the dimensionality for this vector
when parsing line [(line number)] in [(file
name)]
```
+ If the embeddings in a file are not properly formatted, Neptune Analytics reports a Parsing Exception before starting the load. For example, if the column header for the embedding column is not `embedding:vector`, Neptune Analytics would report an error like this:
```
An error occurred (ParsingException) when calling the
ExecuteOpenCypherQuery operation: Invalid data type encountered for header
embedding:Vectttor when parsing line
[~id, name:string, embedding:Vectttor, ~label] in [(file name)]
```
+ If embeddings are present in a file to be loaded but no vector index is present, Neptune Analytics simply ignores the embeddings and loads the graph data without them.
## Vector-search algorithms in Neptune Analytics
Neptune Analytics supports a variety of vector-search algorithms that are listed in the [VSS algorithms](vss-algorithms.md) section.
# Vector-similarity search (VSS) algorithms in Neptune Analytics
Vector similarity search algorithms identify similar vectors based on the vector distance between them.
Neptune Analytics supports the following vector-similarity search algorithms:
**Note**
The following special floating-point values are not supported in Neptune Analytics vector-similarity search algorithms:
**INF** (infinity)
**-INF** (negative infinity)
**NaN** (not-a-number)
**Contents**
+ [The `.vectors.distance` algorithm (deprecated)](vectors-distance.md)
+ [`.vectors.distance` syntax](vectors-distance.md#vectors-distance-syntax)
+ [`.vectors.distance` inputs](vectors-distance.md#vectors-distance-inputs)
+ [`.vectors.distance` outputs](vectors-distance.md#vectors-distance-outputs)
+ [`.vectors.distance` query examples](vectors-distance.md#vectors-distance-query-example)
+ [Sample `.vectors.distance` output](vectors-distance.md#vectors-distance-sample-output)
+ [The `.vectors.distance.byNode` algorithm](vectors.distance.byNode.md)
+ [`.vectors.distance.byNode` syntax](vectors.distance.byNode.md#vectors.distance.byNode-syntax)
+ [`.vectors.distance.byNode` inputs](vectors.distance.byNode.md#vectors.distance.byNode-inputs)
+ [`.vectors.distance.byNode` outputs](vectors.distance.byNode.md#vectors.distance.byNode-outputs)
+ [`.vectors.distance.byNode` query examples](vectors.distance.byNode.md#vectors.distance.byNode-query-example)
+ [Sample `.vectors.distance.byNode` output](vectors.distance.byNode.md#vectors.distance.byNode-sample-output)
+ [The `.vectors.distanceByEmbedding` algorithm (deprecated)](vectors-distance-embedding.md)
+ [`.vectors.distanceByEmbedding` syntax](vectors-distance-embedding.md#vectors-distance-embedding-syntax)
+ [`.vectors.distanceByEmbedding` inputs](vectors-distance-embedding.md#vectors-distance-embedding-inputs)
+ [`.vectors.distanceByEmbedding` outputs](vectors-distance-embedding.md#vectors-distance-embedding-outputs)
+ [`.vectors.distanceByEmbedding` query examples](vectors-distance-embedding.md#vectors-distance-embedding-query-example)
+ [Sample `.vectors.distanceByEmbedding` output](vectors-distance-embedding.md#vectors-distance-embedding-sample-output)
+ [The `.vectors.distance.byEmbedding` algorithm](vectors.distance.byEmbedding.md)
+ [`.vectors.distance.byEmbedding` syntax](vectors.distance.byEmbedding.md#vectors.distance.byEmbedding-syntax)
+ [`.vectors.distance.byEmbedding` inputs](vectors.distance.byEmbedding.md#vectors.distance.byEmbedding-inputs)
+ [`.vectors.distance.byEmbedding` outputs](vectors.distance.byEmbedding.md#vectors.distance.byEmbedding-outputs)
+ [`.vectors.distance.byEmbedding` query examples](vectors.distance.byEmbedding.md#vectors.distance.byEmbedding-query-example)
+ [Sample `.vectors.distance.byEmbedding` output](vectors.distance.byEmbedding.md#vectors.distance.byEmbedding-sample-output)
+ [The `.vectors.get` algorithm](vectors-get.md)
+ [`.vectors.get` syntax](vectors-get.md#vectors-get-syntax)
+ [`.vectors.get` input](vectors-get.md#vectors-get-inputs)
+ [`.vectors.get` outputs](vectors-get.md#vectors-get-outputs)
+ [`.vectors.get` query example](vectors-get.md#vectors-get-query-example)
+ [Sample `.vectors.get` output](vectors-get.md#vectors-get-sample-output)
+ [.vectors.topKByEmbedding algorithm (deprecated)](vectors-topKByEmbedding.md)
+ [`.vectors.topKByEmbedding` syntax](vectors-topKByEmbedding.md#vectors-topKByEmbedding-syntax)
+ [`.vectors.topKByEmbedding` input](vectors-topKByEmbedding.md#vectors-topKByEmbedding-inputs)
+ [`.vectors.topKByEmbedding` outputs](vectors-topKByEmbedding.md#vectors-topKByEmbedding-outputs)
+ [`.vectors.topKByEmbedding` query example](vectors-topKByEmbedding.md#vectors-topKByEmbedding-query-example)
+ [Sample `.vectors.topKByEmbedding` output](vectors-topKByEmbedding.md#vectors-topKByEmbedding-sample-output)
+ [.vectors.topK.byEmbedding algorithm](vectors.topK.byEmbedding.md)
+ [`.vectors.topK.byEmbedding` syntax](vectors.topK.byEmbedding.md#vectors.topK.byEmbedding-syntax)
+ [`.vectors.topK.byEmbedding` input](vectors.topK.byEmbedding.md#vectors.topK.byEmbedding-inputs)
+ [`.vectors.topK.byEmbedding` outputs](vectors.topK.byEmbedding.md#vectors.topK.byEmbedding-outputs)
+ [`.vectors.topK.byEmbedding` query example](vectors.topK.byEmbedding.md#vectors.topK.byEmbedding-query-example)
+ [Sample `.vectors.topKByEmbedding` output](vectors.topK.byEmbedding.md#vectors-topKByEmbedding-sample-output)
+ [.vectors.topKByNode algorithm (deprecated)](vectors-topKByNode.md)
+ [`.vectors.topKByNode` syntax](vectors-topKByNode.md#vectors-topKByNode-syntax)
+ [`.vectors.topKByNode` input](vectors-topKByNode.md#vectors-topKByNode-inputs)
+ [`.vectors.topKByNode` outputs](vectors-topKByNode.md#vectors-topKByNode-outputs)
+ [`.vectors.topKByNode` query example](vectors-topKByNode.md#vectors-topKByNode-query-example)
+ [Sample `.vectors.topKByNode` output](vectors-topKByNode.md#vectors-topKByNode-sample-output)
+ [.vectors.topK.byNode algorithm](vectors.topK.byNode.md)
+ [`.vectors.topK.byNode` syntax](vectors.topK.byNode.md#vectors.topK.byNode-syntax)
+ [`.vectors.topK.byNode` input](vectors.topK.byNode.md#vectors.topK.byNode-inputs)
+ [`.vectors.topK.byNode` outputs](vectors.topK.byNode.md#vectors.topK.byNode-outputs)
+ [`.vectors.topK.byNode` query example](vectors.topK.byNode.md#vectors.topK.byNode-query-example)
+ [Sample `.vectors.topK.byNode` output](vectors.topK.byNode.md#vectors.topK.byNode-sample-output)
+ [.vectors.upsert algorithm](vectors-upsert.md)
+ [`.vectors.upsert` syntax](vectors-upsert.md#vectors-upsert-syntax)
+ [`.vectors.upsert` input](vectors-upsert.md#vectors-upsert-inputs)
+ [`.vectors.upsert` outputs](vectors-upsert.md#vectors-upsert-outputs)
+ [`.vectors.upsert` query examples](vectors-upsert.md#vectors-upsert-query-example)
+ [Sample `.vectors.upsert` output](vectors-upsert.md#vectors-upsert-sample-output)
+ [.vectors.remove algorithm](vectors-remove.md)
+ [`.vectors.remove` syntax](vectors-remove.md#vectors-remove-syntax)
+ [`.vectors.remove` input](vectors-remove.md#vectors-remove-inputs)
+ [`.vectors.remove` outputs](vectors-remove.md#vectors-remove-outputs)
+ [`.vectors.remove` query examples](vectors-remove.md#vectors-remove-query-example)
+ [Sample `.vectors.remove` output](vectors-remove.md#vectors-remove-sample-output)
# The `.vectors.distance` algorithm (deprecated)
The `.vectors.distance` algorithm computes the distance between two nodes based on their embeddings. The default distance is the squared L2 norm.
## `.vectors.distance` syntax
```
MATCH( n {`~id`: "the ID of the source node(s)"} )
MATCH( m {`~id`: "the ID of the target node(s)"} )
CALL neptune.algo.vectors.distance(n, m,
{
metric: The distance computation metric (optional)
}
)
YIELD distance
RETURN n, m, distance
```
## `.vectors.distance` inputs
+ **a source node list** *(required)* – *type:* `Node[]` or `NodeId[]`; *default: none*.
The result of a `MATCH` statement from which you want to get the source for the distance computations.
+ **target node list** *(required)* – *type:* `Node[]` or `NodeId[]`; *default: none*.
The result of a `MATCH` statement from which you want to get the targets of the distance computations.
+ **metric** *(optional)* – *type:* `string` *default: L2Squared*.
The distance metric to use for distance computation.
+ Must be one of [L2Squared, L2, CosineSimilarity, CosineDistance, DotProduct].
+ Case-insensitive.
+ The descriptions for the metrics, where x and y are vectors, x\$1i and y\$1i are the components of x and y vectors, θ is the angle between the x and y vectors, \$1\$1x\$1\$1 denotes the magnitude (length, l2-norm, norm2) of vector x, ∑ denotes summation:
+ L2-Squared: Squared Euclidean distance between two vectors:
![\[L2-Squared: Squared Euclidean distance between two vectors.\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/images/vectors-distance/L2Squared.png)
For more information on L2-Squared, see [ https://en.wikipedia.org/wiki/Euclidean\$1distance\$1Squared\$1Euclidean\$1distance](https://en.wikipedia.org/wiki/Euclidean_distance#Squared_Euclidean_distance).
+ L2: Euclidean distance (L2 norm) between two vectors:
![\[L2: Euclidean distance (L2 norm) between two vectors.\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/images/vectors-distance/L2.png)
For more information on L2, see [ https://en.wikipedia.org/wiki/Euclidean\$1distance](https://en.wikipedia.org/wiki/Euclidean_distance).
+ Dot Product: Inner dot product of two vectors:
![\[Dot Product: Inner dot product of two vectors.\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/images/vectors-distance/dot1.png)
For more information on Dot Product, see [ https://en.wikipedia.org/wiki/Dot\$1product](https://en.wikipedia.org/wiki/Dot_product).
+ Cosine Similarity: Measures the cosine of the angle between two vectors (higher value means more similar):
![\[Cosine Similarity: Measures the cosine of the angle between two vectors (higher value means more similar).\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/images/vectors-distance/cossimi4.png)
Range: [-1, 1]
For more information on Cosine Similarity, see [ https://en.wikipedia.org/wiki/Cosine\$1similarity](https://en.wikipedia.org/wiki/Cosine_similarity).
+ Cosine Distance: Opposite of cosine similarity (lower value means more similar):
![\[Cosine Distance: Opposite of cosine similarity (lower value means more similar).\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/images/vectors-distance/cosdist1.png)
Range: [0, 2]
For more information on Cosine Distance, see [ https://en.wikipedia.org/wiki/Cosine\$1similarity\$1Cosine\$1distance](https://en.wikipedia.org/wiki/Cosine_similarity#Cosine_distance).
**Warning**
Be careful to limit `MATCH(n)` and `MATCH(m)` so that they don't return a large number of nodes. Keep in mind that every pair of `n` and `m` in the join result invokes `.vectors.distance` once. Too many inputs can therefore result in very long runtimes. Use `LIMIT` or put conditions on the `MATCH` clause to restrict its output appropriately.
## `.vectors.distance` outputs
For every pair of source node and target node:
+ **source** – The source node.
+ **target** – The target node.
+ **distance** – The distance between source and target nodes.
## `.vectors.distance` query examples
```
MATCH ( n {`~id`: "106"} )
MATCH ( m {`~id`: "110" } )
CALL neptune.algo.vectors.distance( n, m )
YIELD distance
RETURN n, m, distance
```
```
MATCH ( n {`~id`: "106"} )
MATCH ( m {`~id`: "110"} )
CALL neptune.algo.vectors.distance( n, m, {metric: "CosineSimilarity"} )
YIELD distance
RETURN n, m, distance
```
## Sample `.vectors.distance` output
Here is an example of the output returned by `.vectors.distance` when run against a sample Wikipedia dataset using the following query:
```
aws neptune-graph execute-query \
--graph-identifier ${graphIdentifier} \
--query-string "MATCH (n{`~id`: '0'})
MATCH (m{`~id`: '1'})
CALL neptune.algo.vectors.distance(n, m)
YIELD distance
RETURN n, m, distance" \
--language open_cypher \
/tmp/out.txt
{
"results": [
{
"n": {
"~id": "0",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 0,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "The 24-hour clock is a way of telling the time in which the day runs from midnight to midnight and is divided into 24 hours\\, numbered from 0 to 23. It does not use a.m. or p.m. This system is also referred to (only in the US and the English speaking parts of Canada) as military time or (only in the United Kingdom and now very rarely) as continental time. In some parts of the world\\, it is called railway time. Also\\, the international standard notation of time (ISO 8601) is based on this format."
}
},
"m": {
"~id": "1",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 1,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "A time in the 24-hour clock is written in the form hours:minutes (for example\\, 01:23)\\, or hours:minutes:seconds (01:23:45). Numbers under 10 have a zero in front (called a leading zero); e.g. 09:07. Under the 24-hour clock system\\, the day begins at midnight\\, 00:00\\, and the last minute of the day begins at 23:59 and ends at 24:00\\, which is identical to 00:00 of the following day. 12:00 can only be mid-day. Midnight is called 24:00 and is used to mean the end of the day and 00:00 is used to mean the beginning of the day. For example\\, you would say \"Tuesday at 24:00\" and \"Wednesday at 00:00\" to mean exactly the same time."
}
},
"distance": 27.762847900390626
}
]
}
```
# The `.vectors.distance.byNode` algorithm
The `.vectors.distance.byNode` algorithm computes the distance between two nodes based on their embeddings. The default distance is the squared L2 norm.
## `.vectors.distance.byNode` syntax
```
MATCH( n {`~id`: "the ID of the source node(s)"} )
MATCH( m {`~id`: "the ID of the target node(s)"} )
CALL neptune.algo.vectors.distance.byNode(n, m,
{
metric: The distance computation metric (optional)
}
)
YIELD distance
RETURN n, m, distance
```
## `.vectors.distance.byNode` inputs
+ **a source node list** *(required)* – *type:* `Node[]` or `NodeId[]`; *default: none*.
The result of a `MATCH` statement from which you want to get the source for the distance computations.
+ **target node list** *(required)* – *type:* `Node[]` or `NodeId[]`; *default: none*.
The result of a `MATCH` statement from which you want to get the targets of the distance computations.
+ **metric** *(optional)* – *type:* `string` *default: L2Squared*.
The distance metric to use for distance computation.
+ Must be one of [L2Squared, L2, CosineSimilarity, CosineDistance, DotProduct].
+ Case-insensitive.
+ The descriptions for the metrics, where x and y are vectors, x\$1i and y\$1i are the components of x and y vectors, θ is the angle between the x and y vectors, \$1\$1x\$1\$1 denotes the magnitude (length, l2-norm, norm2) of vector x, ∑ denotes summation:
+ L2-Squared: Squared Euclidean distance between two vectors:
![\[L2-Squared: Squared Euclidean distance between two vectors.\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/images/vectors-distance/L2Squared.png)
For more information on L2-Squared, see [ https://en.wikipedia.org/wiki/Euclidean\$1distance\$1Squared\$1Euclidean\$1distance](https://en.wikipedia.org/wiki/Euclidean_distance#Squared_Euclidean_distance).
+ L2: Euclidean distance (L2 norm) between two vectors:
![\[L2: Euclidean distance (L2 norm) between two vectors.\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/images/vectors-distance/L2.png)
For more information on L2, see [ https://en.wikipedia.org/wiki/Euclidean\$1distance](https://en.wikipedia.org/wiki/Euclidean_distance).
+ Dot Product: Inner dot product of two vectors:
![\[Dot Product: Inner dot product of two vectors.\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/images/vectors-distance/dot1.png)
For more information on Dot Product, see [ https://en.wikipedia.org/wiki/Dot\$1product](https://en.wikipedia.org/wiki/Dot_product).
+ Cosine Similarity: Measures the cosine of the angle between two vectors (higher value means more similar):
![\[Cosine Similarity: Measures the cosine of the angle between two vectors (higher value means more similar).\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/images/vectors-distance/cossimi4.png)
Range: [-1, 1]
For more information on Cosine Similarity, see [ https://en.wikipedia.org/wiki/Cosine\$1similarity](https://en.wikipedia.org/wiki/Cosine_similarity).
+ Cosine Distance: Opposite of cosine similarity (lower value means more similar):
![\[Cosine Distance: Opposite of cosine similarity (lower value means more similar).\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/images/vectors-distance/cosdist1.png)
Range: [0, 2]
For more information on Cosine Distance, see [ https://en.wikipedia.org/wiki/Cosine\$1similarity\$1Cosine\$1distance](https://en.wikipedia.org/wiki/Cosine_similarity#Cosine_distance).
**Warning**
Be careful to limit `MATCH(n)` and `MATCH(m)` so that they don't return a large number of nodes. Keep in mind that every pair of `n` and `m` in the join result invokes `.vectors.distance.byNode` once. Too many inputs can therefore result in very long runtimes. Use `LIMIT` or put conditions on the `MATCH` clause to restrict its output appropriately.
## `.vectors.distance.byNode` outputs
For every pair of source node and target node:
+ **source** – The source node.
+ **target** – The target node.
+ **distance** – The distance between source and target nodes.
## `.vectors.distance.byNode` query examples
```
MATCH ( n {`~id`: "106"} )
MATCH ( m {`~id`: "110" } )
CALL neptune.algo.vectors.distance.byNode( n, m )
YIELD distance
RETURN n, m, distance
```
```
MATCH ( n {`~id`: "106"} )
MATCH ( m {`~id`: "110"} )
CALL neptune.algo.vectors.distance.byNode( n, m, {metric: "CosineSimilarity"} )
YIELD distance
RETURN n, m, distance
```
## Sample `.vectors.distance.byNode` output
Here is an example of the output returned by `.vectors.distance.byNode` when run against a sample Wikipedia dataset using the following query:
```
aws neptune-graph execute-query \
--graph-identifier ${graphIdentifier} \
--query-string "MATCH (n{`~id`: '0'})
MATCH (m{`~id`: '1'})
CALL neptune.algo.vectors.distance.byNode(n, m)
YIELD distance
RETURN n, m, distance" \
--language open_cypher \
/tmp/out.txt
{
"results": [
{
"n": {
"~id": "0",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 0,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "The 24-hour clock is a way of telling the time in which the day runs from midnight to midnight and is divided into 24 hours\\, numbered from 0 to 23. It does not use a.m. or p.m. This system is also referred to (only in the US and the English speaking parts of Canada) as military time or (only in the United Kingdom and now very rarely) as continental time. In some parts of the world\\, it is called railway time. Also\\, the international standard notation of time (ISO 8601) is based on this format."
}
},
"m": {
"~id": "1",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 1,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "A time in the 24-hour clock is written in the form hours:minutes (for example\\, 01:23)\\, or hours:minutes:seconds (01:23:45). Numbers under 10 have a zero in front (called a leading zero); e.g. 09:07. Under the 24-hour clock system\\, the day begins at midnight\\, 00:00\\, and the last minute of the day begins at 23:59 and ends at 24:00\\, which is identical to 00:00 of the following day. 12:00 can only be mid-day. Midnight is called 24:00 and is used to mean the end of the day and 00:00 is used to mean the beginning of the day. For example\\, you would say \"Tuesday at 24:00\" and \"Wednesday at 00:00\" to mean exactly the same time."
}
},
"distance": 27.762847900390626
}
]
}
```
# The `.vectors.distanceByEmbedding` algorithm (deprecated)
The `.vectors.distanceByEmbedding` algorithm computes the distance between an embedding vector and the embedding of an input node. The default distance is the squared L2 norm of the input (source) embedding vector and the embedding vector of the (target) input node.
## `.vectors.distanceByEmbedding` syntax
```
WITH [*an embedding*] as embedding
MATCH( n {`~id`: "the ID of the target node(s)"} )
CALL neptune.algo.vectors.distanceByEmbedding(embedding, n,
{
metric: The distance computation metric (optional)
}
)
YIELD distance
RETURN embedding, n, distance
```
## `.vectors.distanceByEmbedding` inputs
+ **a source embedding list** *(required)* – *type:* `float[]` or `double[]`;.
The mebedding vector from which you want to use as the source for the distance computations.
+ **a target node list** *(required)* – *type:* `Node[]` or `NodeId[]`; *default: none*.
The result of a `MATCH` statement from which you want to source distance computations.
+ **metric** *(optional)* – *type:* `string` *default: L2Squared*.
The distance metric to use for distance computation.
+ Must be one of [L2Squared, L2, CosineSimilarity, CosineDistance, DotProduct].
+ Case-insensitive.
+ The descriptions for the metrics, where x and y are vectors, x\$1i and y\$1i are the components of x and y vectors, θ is the angle between the x and y vectors, \$1\$1x\$1\$1 denotes the magnitude (length, l2-norm, norm2) of vector x, ∑ denotes summation:
+ L2-Squared: Squared Euclidean distance between two vectors:
![\[L2-Squared: Squared Euclidean distance between two vectors.\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/images/vectors-distance/L2Squared.png)
For more information on L2-Squared, see [ https://en.wikipedia.org/wiki/Euclidean\$1distance\$1Squared\$1Euclidean\$1distance](https://en.wikipedia.org/wiki/Euclidean_distance#Squared_Euclidean_distance).
+ L2: Euclidean distance (L2 norm) between two vectors:
![\[L2: Euclidean distance (L2 norm) between two vectors.\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/images/vectors-distance/L2.png)
For more information on L2, see [ https://en.wikipedia.org/wiki/Euclidean\$1distance](https://en.wikipedia.org/wiki/Euclidean_distance).
+ Dot Product: Inner dot product of two vectors:
![\[Dot Product: Inner dot product of two vectors.\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/images/vectors-distance/dot1.png)
For more information on Dot Product, see [ https://en.wikipedia.org/wiki/Dot\$1product](https://en.wikipedia.org/wiki/Dot_product).
+ Cosine Similarity: Measures the cosine of the angle between two vectors (higher value means more similar):
![\[Cosine Similarity: Measures the cosine of the angle between two vectors (higher value means more similar).\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/images/vectors-distance/cossimi4.png)
Range: [-1, 1]
For more information on Cosine Similarity, see [ https://en.wikipedia.org/wiki/Cosine\$1similarity](https://en.wikipedia.org/wiki/Cosine_similarity).
+ Cosine Distance: Opposite of cosine similarity (lower value means more similar):
![\[Cosine Distance: Opposite of cosine similarity (lower value means more similar).\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/images/vectors-distance/cosdist1.png)
Range: [0, 2]
For more information on Cosine Distance, see [ https://en.wikipedia.org/wiki/Cosine\$1similarity\$1Cosine\$1distance](https://en.wikipedia.org/wiki/Cosine_similarity#Cosine_distance).
## `.vectors.distanceByEmbedding` outputs
For every pair of source node and target node:
+ **embedding** – The input source embedding vector.
+ **target** – The target node.
+ **distance** – The distance between the source embedding and the target node.
## `.vectors.distanceByEmbedding` query examples
```
WITH [1.1, 1.2, 1.3, 1.4] as embedding
MATCH (n)
WHERE id(n)="v1"
CALL neptune.algo.vectors.distanceByEmbedding(embedding, n)
YIELD distance
RETURN embedding, n, distance
```
```
WITH [1.1, 1.2, 1.3, 1.4] as embedding
MATCH (n)
WHERE id(n)="v1"
CALL neptune.algo.vectors.distanceByEmbedding(embedding, n, {metric: "CosineSimilarity" })
YIELD distance
return embedding, n, distance
```
```
UNWIND [ {id: "933", embedding: [1,2,3,4]},
{id: "934", embedding: [-1,-2,-3,-4]} ] as entry
MATCH (n:person) WHERE id(n)=entry.id WITH n, entry.embedding as embedding
CALL neptune.algo.vectors.distanceByEmbedding(embedding, n)
YIELD distance
RETURN embedding, n, distance
```
## Sample `.vectors.distanceByEmbedding` output
Here is an example of the output returned by `.vectors.distanceByEmbedding` when run against a sample Wikipedia dataset using the following query:
```
aws neptune-graph execute-query \
--graph-identifier ${graphIdentifier} \
--query-string "***embedding part***
MATCH (n{`~id`: '1'})
CALL neptune.algo.vectors.distanceByEmbedding(embedding, n)
YIELD distance
RETURN embedding, n, distance" \
--language open_cypher \
/tmp/out.txt
{
"results": [
{
"embedding": [***embedding***],
"n": {
"~id": "1",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 1,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "A time in the 24-hour clock is written in the form hours:minutes (for example\\, 01:23)\\, or hours:minutes:seconds (01:23:45). Numbers under 10 have a zero in front (called a leading zero); e.g. 09:07. Under the 24-hour clock system\\, the day begins at midnight\\, 00:00\\, and the last minute of the day begins at 23:59 and ends at 24:00\\, which is identical to 00:00 of the following day. 12:00 can only be mid-day. Midnight is called 24:00 and is used to mean the end of the day and 00:00 is used to mean the beginning of the day. For example\\, you would say \"Tuesday at 24:00\" and \"Wednesday at 00:00\" to mean exactly the same time."
}
},
"distance": 27.762847900390626
}
]
}
```
# The `.vectors.distance.byEmbedding` algorithm
The `.vectors.distance.byEmbedding` algorithm computes the distance between an embedding vector and the embedding of an input node. The default distance is the squared L2 norm of the input embedding vector and the embedding vector of the input node.
## `.vectors.distance.byEmbedding` syntax
```
MATCH( n {`~id`: "the ID of the input node(s)"} )
CALL neptune.algo.vectors.distance.byEmbedding(n,
{
metric: The distance computation metric (optional),
embedding: [*an embedding*] (required)
}
)
YIELD distance
RETURN n, distance
```
## `.vectors.distance.byEmbedding` inputs
+ **an input node list** *(required)* – *type:* `node[]` or `NodeId[]`; *default: none*.
The result of a `MATCH` statement from which you want get the input nodes of the distance computations.
+ **embedding** *(required)* – *type:* `float[]` or `double[]`;.
The input embedding vector from which you want to use for the distance computations. The dimension of the embedding must match the declared dimension of the associated vector index.
The embedding may or may not exist in the database. If not, it can be any vector of the same dimension as is declared in the associated vector index.
+ **metric** *(optional)* – *type:* `string` *default: L2Squared*.
The distance metric to use for distance computation.
+ Must be one of [L2Squared, L2, CosineSimilarity, CosineDistance, DotProduct].
+ Case-insensitive.
+ The descriptions for the metrics, where x and y are vectors, x\$1i and y\$1i are the components of x and y vectors, θ is the angle between the x and y vectors, \$1\$1x\$1\$1 denotes the magnitude (length, l2-norm, norm2) of vector x, ∑ denotes summation:
+ L2-Squared: Squared Euclidean distance between two vectors:
![\[L2-Squared: Squared Euclidean distance between two vectors.\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/images/vectors-distance/L2Squared.png)
For more information on L2-Squared, see [ https://en.wikipedia.org/wiki/Euclidean\$1distance\$1Squared\$1Euclidean\$1distance](https://en.wikipedia.org/wiki/Euclidean_distance#Squared_Euclidean_distance).
+ L2: Euclidean distance (L2 norm) between two vectors:
![\[L2: Euclidean distance (L2 norm) between two vectors.\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/images/vectors-distance/L2.png)
For more information on L2, see [ https://en.wikipedia.org/wiki/Euclidean\$1distance](https://en.wikipedia.org/wiki/Euclidean_distance).
+ Dot Product: Inner dot product of two vectors:
![\[Dot Product: Inner dot product of two vectors.\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/images/vectors-distance/dot1.png)
For more information on Dot Product, see [ https://en.wikipedia.org/wiki/Dot\$1product](https://en.wikipedia.org/wiki/Dot_product).
+ Cosine Similarity: Measures the cosine of the angle between two vectors (higher value means more similar):
![\[Cosine Similarity: Measures the cosine of the angle between two vectors (higher value means more similar).\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/images/vectors-distance/cossimi4.png)
Range: [-1, 1]
For more information on Cosine Similarity, see [ https://en.wikipedia.org/wiki/Cosine\$1similarity](https://en.wikipedia.org/wiki/Cosine_similarity).
+ Cosine Distance: Opposite of cosine similarity (lower value means more similar):
![\[Cosine Distance: Opposite of cosine similarity (lower value means more similar).\]](http://docs.aws.amazon.com/neptune-analytics/latest/userguide/images/vectors-distance/cosdist1.png)
Range: [0, 2]
For more information on Cosine Distance, see [ https://en.wikipedia.org/wiki/Cosine\$1similarity\$1Cosine\$1distance](https://en.wikipedia.org/wiki/Cosine_similarity#Cosine_distance).
## `.vectors.distance.byEmbedding` outputs
For every target node:
+ **target** – The target node.
+ **distance** – The distance between the source embedding and the embedding of the target node.
## `.vectors.distance.byEmbedding` query examples
```
MATCH (n)
WHERE id(n)="v1"
CALL neptune.algo.vectors.distance.byEmbedding(n, {embedding: [1.1, 1.2, 1.3, 1.4], metric: "L2Squared"})
YIELD distance
RETURN n, distance
```
```
MATCH (n:person) WHERE id(n)=entry.id WITH n
CALL neptune.algo.vectors.distance.byEmbedding(n, {embedding: [1,2,3,4], metric: "CosineSimilarity"})
YIELD distance
RETURN n, distance
```
## Sample `.vectors.distance.byEmbedding` output
Here is an example of the output returned by `.vectors.distance.byEmbedding` when run against a sample Wikipedia dataset using the following query:
```
aws neptune-graph execute-query \
--graph-identifier ${graphIdentifier} \
--query-string "MATCH (n{`~id`: '1'})
CALL neptune.algo.vectors.distance.byEmbedding(n, {embedding: [*an embedding*]})
YIELD distance
RETURN n, distance" \
--language open_cypher \
/tmp/out.txt
{
"results": [
{
"n": {
"~id": "1",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 1,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "A time in the 24-hour clock is written in the form hours:minutes (for example\\, 01:23)\\, or hours:minutes:seconds (01:23:45). Numbers under 10 have a zero in front (called a leading zero); e.g. 09:07. Under the 24-hour clock system\\, the day begins at midnight\\, 00:00\\, and the last minute of the day begins at 23:59 and ends at 24:00\\, which is identical to 00:00 of the following day. 12:00 can only be mid-day. Midnight is called 24:00 and is used to mean the end of the day and 00:00 is used to mean the beginning of the day. For example\\, you would say \"Tuesday at 24:00\" and \"Wednesday at 00:00\" to mean exactly the same time."
}
},
"distance": 27.762847900390626
}
]
}
```
# The `.vectors.get` algorithm
The `.vectors.get` algorithm retrieves the embedding for a node.
## `.vectors.get` syntax
```
MATCH( n {`~id`: "the ID of the node"} )
CALL neptune.algo.vectors.get(n)
YIELD embedding
RETURN n, embedding
```
## `.vectors.get` input
+ **a source node or nodes** *(required)* – *type:* `Node[]` or `NodeId[]`; *default: none*.
The result of a `MATCH` statement that produces the node(s) for which you want to retrieve the embedding.
**Warning**
Be careful to limit `MATCH(n)` so that it doesn't return a large number of nodes. Keep in mind that every source node in the `n` result invokes `.vectors.get` once. Too many inputs can therefore result in very long runtimes. Use `LIMIT` or put conditions on the `MATCH` clause to restrict its output appropriately.
## `.vectors.get` outputs
For each source node provided:
+ **node** – The source node.
+ **embedding** – The embedding of that source node.
## `.vectors.get` query example
```
MATCH ( n {`~id`: "0"} )
CALL neptune.algo.vectors.get(n)
YIELD embedding
RETURN n, embedding
```
## Sample `.vectors.get` output
Here is an example of the output returned by `.vectors.get` when run against the sample Wikipedia dataset using the following query:
```
aws neptune-graph execute-query \
--graph-identifier ${graphIdentifier} \
--query-string "MATCH ( n {`~id`: '0'} )
CALL neptune.algo.vectors.get(n)
YIELD embedding
RETURN n, embedding" \
--language open_cypher \
/tmp/out.txt
{
"results": [
{
"n": {
"~id": "0",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 0,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "The 24-hour clock is a way of telling the time in which the day runs from midnight to midnight and is divided into 24 hours\\, numbered from 0 to 23. It does not use a.m. or p.m. This system is also referred to (only in the US and the English speaking parts of Canada) as military time or (only in the United Kingdom and now very rarely) as continental time. In some parts of the world\\, it is called railway time. Also\\, the international standard notation of time (ISO 8601) is based on this format."
}
},
"embedding": [
0.07711287587881088,
0.3197174072265625,
-0.2051590085029602,
0.6302579045295715,
0.032093219459056857,
0.200703963637352,
0.16665680706501008,
-0.31295087933540347,
0.17575109004974366,
0.5308129191398621,
-0.37528499960899355,
0.3338659405708313,
-0.046272162348032,
0.07841536402702332,
-0.3490406274795532,
0.27182886004447939,
0.3073517680168152,
-0.08306130766868592,
0.5035958886146545,
0.254621684551239,
-0.40407684445381167,
0.28878292441368105,
-0.22588828206062318,
-0.13185778260231019,
-0.21559733152389527,
0.4900434613227844,
0.03866531699895859,
0.507415771484375,
-0.3067346513271332,
0.10740984976291657,
0.08998646587133408,
-0.2652775049209595,
-0.28492602705955508,
0.33600345253944399,
-0.27227747440338137,
0.3691731095314026,
-0.2815995514392853,
0.0856710895895958,
-0.13187488913536073,
0.4753035008907318,
-0.2241700142621994,
0.20263174176216126,
0.4390721619129181,
0.06424559652805329,
0.2463042289018631,
-0.39631763100624087,
0.2971232533454895,
0.2415716052055359,
-0.02803819440305233,
0.32105034589767458,
-0.02222033031284809,
-0.008510420098900795,
-0.00032598740654066205,
0.031057516112923623,
-0.5332233309745789,
0.45022767782211306,
-0.6829474568367004,
1.3313145637512208,
0.19445496797561646,
-0.15697629749774934,
-0.09996363520622254,
-0.2786232829093933,
-0.09833164513111115,
-0.17644722759723664,
0.11717787384986878,
0.2820119559764862,
0.029635537415742875,
0.5247654914855957,
0.5323811173439026,
-0.06254086643457413,
-0.05274389684200287,
0.3877565860748291,
0.43260684609413149,
0.5207982063293457,
-0.27160540223121645,
-0.06000519543886185,
-0.032806672155857089,
-0.3594319522380829,
0.4218965470790863,
-0.3766363263130188,
0.44727250933647158,
-0.04586323723196983,
0.06902860850095749,
0.3030509352684021,
0.18945887684822083,
0.21681705117225648,
-0.014492596499621868,
-0.38649576902389529,
-0.1129651814699173,
0.050081491470336917,
-0.01697717048227787,
0.1415158063173294,
-0.3284287750720978,
-0.02309800498187542,
-0.2051207274198532,
-0.017861712723970414,
-0.07372242212295532,
-0.12263767421245575,
0.21828559041023255,
-0.36898064613342287,
0.3558262288570404,
-0.16924124956130982,
-0.31757786870002749,
0.5452765226364136,
0.24666202068328858,
-0.08289600908756256,
-0.14674079418182374,
-0.18049933016300202,
0.3646247982978821,
0.42489132285118105,
0.0909421369433403,
-0.1764664500951767,
0.22471413016319276,
0.049531541764736179,
-0.022898104041814805,
0.08607156574726105,
0.14532636106014253,
-0.205774188041687,
-0.3457978069782257,
-1.2771626710891724,
0.2826114892959595,
0.2066900134086609,
-0.3884444832801819,
-0.3564482629299164,
-0.25118574500083926,
-0.728326141834259,
0.5217206478118897,
-0.43305152654647829,
0.3510914444923401,
0.5106240510940552,
-0.11594267934560776,
0.43993058800697329,
0.25412991642951968,
0.4275965392589569,
0.1463870108127594,
0.3510439395904541,
0.1619710624217987,
0.11160195618867874,
-0.22760489583015443,
-0.23652249574661256,
0.05374380201101303,
0.7251803278923035,
-0.13991153240203858,
0.9363659024238586,
-0.05858418717980385,
0.5233941674232483,
0.12388131022453308,
0.6248424649238586,
-0.11751417070627213,
0.09689709544181824,
0.7467237710952759,
0.2247271090745926,
-0.6747357845306397,
-0.16039365530014039,
-0.41555172204971316,
-0.04566565155982971,
0.21260707080364228,
0.2549103796482086,
0.24795542657375337,
0.5625612735748291,
0.8036459684371948,
0.15800043940544129,
0.04797195643186569,
-0.15839435160160066,
-0.06506697088479996,
-0.2577322721481323,
0.3262946903705597,
0.5458049178123474,
0.616370439529419,
-0.35092639923095705,
0.048758912831544879,
0.11522434651851654,
0.04175107553601265,
-0.12269306182861328,
0.1227836161851883,
0.4020257890224457,
0.07093577086925507,
-0.1880340874195099,
0.5334663391113281,
0.46888044476509097,
0.18104688823223115,
0.30756646394729617,
0.29316428303718569,
-0.10604366660118103,
0.44999250769615176,
0.18227706849575044,
0.5962150692939758,
0.38278165459632876,
-0.40461188554763796,
0.17775404453277589,
-0.16349074244499207,
0.06950787454843521,
0.7547341585159302,
-0.4842711389064789,
0.4062837064266205,
0.09000574052333832,
0.03859427571296692,
0.24143263697624207,
-0.3383118510246277,
0.3363209366798401,
0.10778547078371048,
0.3429640233516693,
-0.20395530760288239,
0.011477324180305004,
0.6145590543746948,
-0.5488739609718323,
-0.26194247603416445,
-0.09723474085330963,
-0.19020821154117585,
-0.18068274855613709,
0.1601778119802475,
0.038950759917497638,
0.6372026205062866,
-0.12897184491157533,
0.10720998793840409,
0.13482464849948884,
-0.07540713250637055,
-0.0881727784872055,
0.5626690983772278,
-0.31975486874580386,
-0.029084375128149987,
0.43618619441986086,
0.32975345849990847,
-0.4053913652896881,
0.15788795053958894,
-0.3212168216705322,
-0.20272433757781983,
-0.8973743319511414,
0.060059018433094028,
-0.014103145338594914,
-0.3387225568294525,
-0.49839726090431216,
-0.011007139459252358,
-0.16101065278053285,
-0.20850643515586854,
0.4891682267189026,
0.33551496267318728,
-0.23595896363258363,
-0.4257577359676361,
-0.48884832859039309,
0.48760101199150088,
0.34031161665916445,
0.1722799688577652,
-0.35575979948043826,
0.629051923751831,
-0.8014369010925293,
0.575096607208252,
0.421142578125,
-0.2668846547603607,
-0.046029768884181979,
0.2791147530078888,
-0.22112232446670533,
0.02008579671382904,
0.22087614238262177,
-0.17961964011192323,
0.4235396981239319,
0.295818567276001,
-0.18260923027992249,
0.3227207660675049,
0.11412205547094345,
0.04591478034853935,
0.5127033591270447,
0.428005576133728,
0.20718106627464295,
0.18405631184577943,
-0.22416146099567414,
0.4277373254299164,
0.5384698510169983,
0.04109276458621025,
0.5105301141738892,
0.473961740732193,
-0.6853302717208862,
-0.16557902097702027,
-0.12704522907733918,
0.0026600745040923359,
0.5272349715232849,
0.12121742218732834,
0.427141010761261,
-0.3047095239162445,
0.5948843359947205,
0.335798442363739,
0.35749775171279909,
-0.18497343361377717,
0.26501506567001345,
0.1564970314502716,
0.4210122525691986,
-0.1915784478187561,
0.057152874767780307,
-0.28498271107673647,
0.04969947412610054,
0.7697478532791138,
0.5546697974205017,
0.0958070456981659,
-0.3533228933811188,
0.4784282147884369,
0.624963104724884,
0.2151053100824356,
0.17361000180244447,
0.22527147829532624,
-0.12481484562158585,
0.4212929904460907,
-0.2926572859287262,
0.2562543749809265,
0.38751208782196047,
0.1340814083814621,
0.0680900365114212,
0.2952287793159485,
0.12217980623245239,
-0.2869758605957031,
0.15682946145534516,
-0.022066200152039529,
-0.09002991020679474,
-0.2826828360557556,
0.84619140625,
0.7544476985931397,
0.5953861474990845,
0.6517565250396729,
-0.07932830601930618,
0.22802823781967164,
-0.135965958237648,
-0.8263510465621948,
-0.6325801610946655,
-0.5928561091423035,
0.4108763635158539,
0.0964483916759491,
-0.5045000910758972,
-0.06772734969854355,
-0.79107666015625,
0.060380879789590839,
0.015578197315335274,
0.32540079951286318,
-0.044692762196063998,
-0.17132098972797395,
-0.19123415648937226,
0.17911623418331147,
0.3269428014755249,
-0.22874118387699128,
0.4686919152736664,
-0.15749554336071015,
-0.25185921788215639,
-0.21561351418495179,
-0.10132477432489395,
-0.057977184653282168,
0.09759098291397095,
0.16202516853809358,
0.01888692006468773,
0.1724688857793808,
-0.3449697196483612,
0.4449881315231323,
0.10185430943965912,
-0.2976726293563843,
0.06075461208820343,
0.21909406781196595,
-0.07409229874610901,
0.6881160140037537,
0.17447273433208466,
-0.048471711575984958,
0.5318611264228821,
0.30954766273498537,
-0.24350836873054505,
0.14386573433876038,
-0.10827953368425369,
0.08575868606567383,
0.14200334250926972,
0.5095603466033936,
-0.025056177750229837,
0.24901045858860017,
-0.23696841299533845,
-0.03630203381180763,
0.45206722617149355,
0.5019969344139099,
-0.21705971658229829,
-0.08452687412500382,
-0.10376924276351929,
-0.3200875520706177,
-0.2048267275094986,
-0.2703971266746521,
0.2925371825695038,
0.3755778670310974,
0.2522588074207306,
0.22964833676815034,
0.7995960116386414,
0.12206973880529404,
0.2896155118942261,
0.04163726791739464,
-0.12602514028549195,
0.004978220444172621,
0.3399927020072937,
0.09124521911144257,
-0.5452605485916138,
0.2247130423784256,
0.23503662645816804,
0.06750215590000153,
-0.2884872257709503,
-0.2791622579097748,
-0.1780446618795395,
-0.44350507855415347,
-0.1840016394853592,
0.8970789909362793,
-0.3687478303909302,
0.36603569984436037,
0.23560358583927155,
0.020292289555072786,
0.2446030080318451,
4.3314642906188969,
0.194863960146904,
-0.10218192636966706,
0.5695234537124634,
0.016988292336463929,
-0.15768325328826905,
0.050476688891649249,
0.09948820620775223,
-0.06554386019706726,
0.22301962971687318,
-0.05468735471367836,
0.29051196575164797,
0.12100572139024735,
0.4127441644668579,
0.1667146235704422,
0.0587792843580246,
-0.09758614003658295,
-0.20510408282279969,
-0.21746976673603059,
0.43335747718811037,
-0.32159093022346499,
0.6942153573036194,
0.6173154711723328,
0.3104712665081024,
0.5751503109931946,
0.4174514412879944,
-0.2948107421398163,
0.3532458245754242,
0.4869029223918915,
0.3115881681442261,
0.28135108947753909,
0.38450825214385989,
0.016915690153837205,
-0.11598393321037293,
-0.32250434160232546,
-0.06988134980201721,
0.22417351603507996,
-0.35582518577575686,
0.2677224576473236,
0.008019124157726765,
-0.19177919626235963,
0.5731900334358215,
-0.03540642186999321,
0.43302130699157717,
0.1796148121356964,
-0.005056577268987894,
0.37953320145606997,
0.13488957285881043,
0.7240068912506104,
-0.3088097870349884,
0.5610846281051636,
-0.29582735896110537,
-0.20909856259822846,
-0.2881403863430023,
0.10329002141952515,
0.49255961179733279,
0.14558906853199006,
0.41020694375038149,
0.04002099484205246,
-0.24476903676986695,
-0.389543354511261,
0.3901459574699402,
0.6170359253883362,
0.18917717039585114,
-0.41235554218292239,
-0.19313344359397889,
-0.10294703394174576,
0.5560699105262756,
0.5773581266403198,
-0.17282086610794068,
0.28679269552230837,
0.34322652220726015,
-0.07227988541126251,
-0.5244243741035461,
-0.26529040932655337,
-0.11131077259778977,
-0.19524210691452027,
0.4082769453525543,
-0.009217939339578152,
-0.1462743580341339,
0.7264918684959412,
-0.09149657934904099,
-0.3374916911125183,
-0.05742226541042328,
-0.3913151025772095,
0.7185215950012207,
-0.3785516619682312,
-0.00010882654169108719,
0.6655824780464172,
0.4194306433200836,
0.3726831376552582,
-0.014721312560141087,
0.5345744490623474,
0.33022087812423708,
-0.06344814598560333,
-0.1560882031917572,
0.22698232531547547,
-3.8697707653045656,
0.06812435388565064,
-0.4368731677532196,
-0.07041455805301666,
-0.015291529707610608,
-0.41140303015708926,
0.31612321734428408,
0.2914712429046631,
-0.3867192566394806,
-0.026363473385572435,
-0.08788029104471207,
-0.10701339691877365,
-0.2673511505126953,
0.27538666129112246,
-0.3661351501941681,
0.5879861116409302,
0.06352981925010681,
0.15547777712345124,
0.0863194614648819,
-0.021183960139751436,
0.428565114736557,
0.04859453812241554,
0.35721391439437868,
-0.3864029347896576,
-0.20986808836460114,
0.15433000028133393,
0.25567296147346499,
0.25359275937080386,
-0.4783596396446228,
-0.010366495698690415,
0.4777776598930359,
-0.029405448585748674,
0.3631121814250946,
-0.18738743662834168,
0.2193489819765091,
0.7861229777336121,
-0.01961355283856392,
0.16653983294963838,
-0.4193624258041382,
0.3085209131240845,
-0.03517897054553032,
-0.035910699516534808,
0.37241387367248537,
-0.13769084215164185,
-0.08015040308237076,
0.4384872615337372,
-0.12396809458732605,
0.15661391615867616,
-0.3919837176799774,
-0.6586825251579285,
0.5687432885169983,
0.0396936871111393,
-0.09660491347312927,
0.05788198113441467,
0.48911261558532717,
0.5213083028793335,
0.3355415165424347,
-0.006735790055245161,
-0.11381038278341294,
0.09182903915643692,
-0.11055094748735428,
-0.28275448083877566,
0.24975340068340302,
0.11746659129858017,
-0.42452141642570498,
-0.2323901206254959,
-0.38694220781326296,
0.015501483343541623,
0.6440262198448181,
-0.3121536672115326,
-0.08778296411037445,
-0.14549347758293153,
0.01749151013791561,
-0.5398207902908325,
0.4124368131160736,
0.5154116749763489,
-0.34769660234451296,
0.5662841796875,
0.4989481270313263,
0.06761053949594498,
0.014184223487973214,
0.601079523563385,
-0.3859538435935974,
0.3446619212627411,
2.190366744995117,
0.4051366150379181,
2.288928508758545,
0.5293960571289063,
-0.3505767583847046,
0.5397417545318604,
-0.6520821452140808,
0.4239364266395569,
0.2618080675601959,
0.20174439251422883,
0.030146604403853418,
0.0610184520483017,
0.062213074415922168,
-0.11276254057884217,
-0.1301877349615097,
-0.19404706358909608,
0.5268515348434448,
-0.7370991706848145,
0.028712594881653787,
-0.4024544954299927,
0.18225152790546418,
0.7267741560935974,
-0.2734072208404541,
0.1759040206670761,
-0.2950340211391449,
0.14166314899921418,
0.6515365242958069,
-0.29643580317497256,
-0.06734377890825272,
0.09662584215402603,
-0.010966300964355469,
-0.3204823136329651,
0.6417866349220276,
-0.051218003034591678,
-0.008819818496704102,
0.5098630785942078,
-0.21459998190402986,
4.437846660614014,
-0.24779054522514344,
0.018799694254994394,
-0.01747281290590763,
-0.0487254373729229,
0.6121163964271545,
0.4686623811721802,
-0.22926479578018189,
-0.03692511469125748,
-0.4286654591560364,
0.46073317527770998,
0.16875289380550385,
-0.014255600981414318,
-0.07684683054685593,
0.12223237752914429,
-0.30599895119667055,
0.39215049147605898,
0.22453786432743073,
0.5624862313270569,
-0.011985340155661106,
0.05180392041802406,
0.030400553718209268,
0.08391892164945603,
0.10214067250490189,
-0.4449590742588043,
0.2225639522075653,
0.3862999975681305,
0.24732927978038789,
-0.05571140721440315,
-0.021564822643995286,
0.28468334674835207,
5.213898658752441,
0.13289497792720796,
-0.1400047093629837,
-0.39865049719810488,
0.12139834463596344,
0.45539018511772158,
-0.1865275651216507,
-0.08270177245140076,
-0.38520801067352297,
0.08869948983192444,
-0.05266271159052849,
0.14364486932754517,
-0.2860695719718933,
0.4430652856826782,
0.7777798771858215,
0.21114271879196168,
-0.358752578496933,
-0.3664247989654541,
0.6665846109390259,
-0.40493687987327578,
0.1747705042362213,
-0.06670021265745163,
0.20972059667110444,
-0.19101694226264954,
0.23892535269260407,
-0.08149895817041397,
0.018510373309254648,
0.8112999796867371,
0.07871513813734055,
0.09570053964853287,
0.5030911564826965,
0.21463628113269807,
-0.31457462906837466,
0.3051794767379761,
-0.39506298303604128,
0.06605447828769684,
0.6144300699234009,
-0.4566810429096222,
0.3146623373031616,
0.1887989640235901,
0.9544244408607483,
0.5103438496589661,
-0.4859951138496399,
-0.32647767663002016,
-0.07584235072135925,
0.21474787592887879,
-0.1920636147260666,
-0.4472030997276306,
0.08618132770061493,
-0.17384092509746552,
-0.20969024300575257,
-0.1831870973110199,
0.8782939314842224,
-0.15720084309577943,
0.37347128987312319,
0.5088165998458862,
0.29395583271980288,
-0.3580363988876343,
-0.17590023577213288,
-0.508141279220581,
0.4661521315574646,
0.142064169049263,
-0.05615571141242981,
0.592810869216919,
0.37807324528694155,
-0.14052101969718934,
-0.19951890408992768,
-0.12800109386444093,
0.748070478439331,
0.13753947615623475,
-0.08446942269802094,
0.3747580945491791,
-0.12847286462783814,
-0.13892321288585664,
0.08525972813367844,
0.12516680359840394,
0.5701874494552612,
-0.24708901345729829,
0.0679594948887825,
0.10870008915662766,
0.20561885833740235,
-0.7872452139854431,
0.07303950190544129,
0.35694700479507449,
0.245212584733963,
0.3299793303012848,
-0.010669616051018238,
-0.12047348916530609,
0.3540535271167755,
0.32180890440940859,
0.3066200911998749,
0.021576205268502237,
0.17679384350776673,
-0.23050960898399354,
0.1292697787284851,
0.022921407595276834,
0.5460971593856812,
0.3612038493156433,
0.1963733434677124,
0.4622957706451416,
0.16855642199516297,
0.2564740478992462,
-0.27637141942977908,
-0.16345584392547608,
0.08119463175535202,
0.07851938903331757,
-0.5181471109390259,
-0.5290305614471436,
0.5271350741386414,
0.3391841650009155,
0.501441240310669,
0.740936279296875,
-0.26713573932647707,
0.030347898602485658,
0.05174243822693825
]
}
]
}
```
# .vectors.topKByEmbedding algorithm (deprecated)
The `.vectors.topKByEmbedding` algorithm finds the `topK` nearest neighbors of an embedding based on the distance of their vector embeddings.
## `.vectors.topKByEmbedding` syntax
```
CALL neptune.algo.vectors.topKByEmbedding(
[an embedding (required)],
{
topK: the number of result nodes to return (optional, default: 10),
concurrency: the number of cores to use to run the algorithm (optional)
}
)
YIELD embedding, node, score
RETURN embedding, node, score
```
## `.vectors.topKByEmbedding` input
+ **an embedding** *(required)* *type:* a list of floating-point values.
The source input embedding to use to compute the distance to the embeddings of the candidate target nodes. The dimension of the embedding must match the declared dimension of the associated vector index.
The embedding may or may not exist in the database. If not, it can be any vector of the same dimension as is declared in the associated vector index.
+ **topK** *(optional)* *type:* a positive integer; *default:* 10.
The number of result nodes to return.
+ **concurrency** *(optional)* – *type:* 0 or 1; *default:* 0.
Controls the number of concurrent threads used to run the algorithm.
If set to `0`, uses all available threads to complete execution of the individual algorithm invocation. If set to `1`, uses a single thread. This can be useful when requiring the invocation of many algorithms concurrently.
## `.vectors.topKByEmbedding` outputs
For each node returned:
+ **embedding** – The input embedding.
+ **node** – A node whose embedding is at one of the `topK` nearest distances from the input embedding.
+ **score** – The distance between the input embedding and the embedding of this node.
## `.vectors.topKByEmbedding` query example
You can provide the embedding explicitly in the query, although embeddings tend to be very large:
```
CALL neptune.algo.vectors.topKByEmbedding(
[0.1, 0.2, 0.3, ...],
{
topK: 7,
concurrency: 1
}
)
YIELD embedding, node, score
RETURN embedding, node, score
```
Most often, you will by generating embeddings to pass to the algorithm. For example:
```
MATCH ( n:airport {code: 'ANC'} )
CALL neptune.algo.vectors.get(n) YIELD embedding AS vector WITH vector
CALL neptune.algo.vectors.topKByEmbedding(
vector,
{
topK: 10,
concurrency: 1
}
)
YIELD node, score
RETURN vector, node, score
```
**Warning**
In queries like the one above, be careful to limit `MATCH(n)` so that it doesn't return a large number of nodes. Keep in mind that every node in `n` invokes a separate run of both `.vectors.get` and `.vectors.topKByEmbedding`. Too many inputs can therefore result in very long runtimes. Use `LIMIT` or put conditions on the `MATCH` clause to restrict its output appropriately.
## Sample `.vectors.topKByEmbedding` output
Here is an example of the output returned by `.vectors.topKByEmbedding` when run against the sample Wikipedia dataset using the following query:
```
aws neptune-graph execute-query \
--graph-identifier ${graphIdentifier} \
--query-string "MATCH ( n {`~id`: '0'} )
CALL neptune.algo.vectors.get(n) YIELD embedding AS vector
CALL neptune.algo.vectors.topKByEmbedding( vector, { topK: 3 })
YIELD node, score
RETURN node, score"
--language open_cypher \
/tmp/out.txt
{
"results": [
{
"node": {
"~id": "0",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 0,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "The 24-hour clock is a way of telling the time in which the day runs from midnight to midnight and is divided into 24 hours\\, numbered from 0 to 23. It does not use a.m. or p.m. This system is also referred to (only in the US and the English speaking parts of Canada) as military time or (only in the United Kingdom and now very rarely) as continental time. In some parts of the world\\, it is called railway time. Also\\, the international standard notation of time (ISO 8601) is based on this format."
}
},
"score": 0.0
},
{
"node": {
"~id": "2",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 2,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "However\\, the US military prefers not to say 24:00 - they do not like to have two names for the same thing\\, so they always say \"23:59\"\\, which is one minute before midnight."
}
},
"score": 24.000200271606447
},
{
"node": {
"~id": "3",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 3,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "24-hour clock time is used in computers\\, military\\, public safety\\, and transport. In many Asian\\, European and Latin American countries people use it to write the time. Many European people use it in speaking."
}
},
"score": 25.013729095458986
}
]
}
```
# .vectors.topK.byEmbedding algorithm
The `.vectors.topKByEmbedding` algorithm finds the `topK` nearest neighbors of an embedding based on the distance of their vector embeddings.
## `.vectors.topK.byEmbedding` syntax
```
CALL neptune.algo.vectors.topK.byEmbedding(
{
embedding: [*an embedding*] (required),
topK: the number of result nodes to return (optional, default: 10),
vertexFilter: a json structure that encodes vertex label or property filters (optional, default: empty),
concurrency: the number of cores to use to run the algorithm (optional, default: 0)
}
)
YIELD node, score
RETURN node, score
```
## `.vectors.topK.byEmbedding` input
+ **embedding** *(required)* *type:* float[] or double[].
The input embedding to use to compute the distance to the embeddings of the candidate target nodes. The dimension of the embedding must match the declared dimension of the associated vector index.
The embedding may or may not exist in the database. If not, it can be any vector of the same dimension as is declared in the associated vector index. Note that the input embedding must be static, aka, the input embedding can't be the output of another query.
+ **topK** *(optional)* *type:* a positive integer; *default:* 10.
The number of result nodes to return.
+ **vertexFilter** *(optional)* *type:* a json string *default:* empty.
The vertexFilter is a json structure encoding filters to use on the vertex labels and properties during computation. In it, there are two operation types: a joiner operation and a single operation. A joiner operation includes andAll and orAll , which is an array of joiner and/or single operations. A single operation includes the rest of the filters. A vertex filter can be used for either vertex labels or vertex properties or a combination of both. Among the single operations, only equals and notEquals support vertex label filtering. The details of all the operations are as follows:
+ *andAll:* Nodes are returned if their properties fulfill all the filter conditions inside this list. It is an array of joiner and/or single operations. It must contain minimum two items.
Example: \$1andAll: [\$1equals:\$1property: “\$1label”, value: “Airport”\$1\$1, \$1greaterThan:\$1property: “runways”, value: 3\$1\$1]\$1 → the Airport vertices that have more than 3 runways.
+ *orAll:* Nodes are returned if their properties fulfill all the filter conditions inside this list. It is an array of joiner and/or single operations. It must contain minimum two items.
Example: \$1orAll: [\$1equals:\$1property: “dist”, value: 10\$1\$1, \$1notEquals:\$1property: “runways”, value: “2”\$1\$1]\$1 → the vertices whose dist is equals to 10 or whose runways is not equal to 2.
+ *equals:* Nodes are returned if they contain a property whose name matches the property and whose value matches the value, or they have the vertex label whose label name matches the value.
The property must be a string. It can either be a vertex property name or \$1label.
The value can be boolean, numeric or string if the property is a vertex property. The value can only be string if the property is \$1label.
Example for vertex property: \$1equals:\$1property: “dist”, value: 10\$1\$1
Example for vertex label: \$1equals:\$1property: “\$1label”, value: “Person”\$1\$1
+ *notEquals:* Nodes are returned if they contain a property whose name matches the property and whose value doesn’t match the value , or they have the vertex label whose label name doesn’t match the value.
The property must be a string. It can either be a vertex property name or \$1label.
The value can be boolean, numeric or string if the property is a vertex property. The value can only be string if the property is \$1label.
Example for vertex property: \$1notEquals:\$1property: “dist”, value: 10\$1\$1
Example for vertex label: \$1notEquals:\$1property: “\$1label”, value: “Person”\$1\$1
+ *greaterThan:* Nodes are returned if they contain a property whose name matches the property and whose value is greater than the value. The value must be numeric.
Example: \$1greaterThan:\$1property: “dist”, value: 10\$1\$1
+ *greaterThanOrEquals:* Nodes are returned if they contain a property whose name matches the property and whose value is greater than or equal to the value. The value must be numeric.
+ *lessThan:* Nodes are returned if they contain a property whose name matches the property and whose value is less than the value. The value must be numeric.
Example: \$1lessThan:\$1property: “dist”, value: 10\$1\$1
+ *lessThanOrEquals:* Nodes are returned if they contain a property whose name matches the property and whose value is less than or equal to the value. The value must be numeric.
Example: \$1lessThanOrEquals:\$1property: “dist”, value: 10\$1\$1
+ *in:* Nodes are returned if they contain a property whose name matches the property and whose value is in the specified value list, or they have the vertex label whose label name matches the values in the value list.
The property must be a string. It can either be a vertex property name or \$1label.
The value list can be a mix list of booleans, numbers or strings if the property is a vertex property. The value can only be a list of strings if the property is \$1label.
Example for vertex property: \$1in:\$1property: “country”, value: [“US”, “UK”]\$1\$1
Example for vertex label: \$1in:\$1property: “\$1label”, value: [“US”, “UK”]\$1\$1
+ *notIn:* Nodes are returned if they contain a property whose name matches the property and whose value is not in the specified value list, or they have the vertex label whose label name does not match the values in the value list.
The property must be a string. It can either be a vertex property name or \$1label.
The value list can be a mix list of booleans, numbers or strings if the property is a vertex property. The value can only be a list of strings if the property is \$1label.
Example for vertex property: \$1in:\$1property: “country”, value: [“US”, “UK”]\$1\$1
Example for vertex label: \$1in:\$1property: “\$1label”, value: [“US”, “UK”]\$1\$1
+ *startsWith:* Nodes are returned if they contain a property whose name matches the property and whose value starts with the value. The value must be a string.
Example: \$1startsWith:\$1property: “country”, value “U”\$1\$1
+ *stringContains:* Nodes are returned if they contain a property whose name matches the property and whose value is one of the following:
A string that contains the value as a substring. The following example would return data sources with an animal property that contains the substring at (for example cat).
Example: \$1stringContains: \$1 property: "animal", value: "at" \$1\$1
+ **concurrency** *(optional)* – *type:* 0 or 1; *default:* 0.
Controls the number of concurrent threads used to run the algorithm.
If set to `0`, uses all available threads to complete execution of the individual algorithm invocation. If set to `1`, uses a single thread. This can be useful when requiring the invocation of many algorithms concurrently.
## `.vectors.topK.byEmbedding` outputs
For each node returned:
+ **node** – A node whose embedding is at one of the `topK` nearest distances from the input embedding.
+ **score** – The squared Euclidean distance between the input embedding and the embedding of this node.
## `.vectors.topK.byEmbedding` query example
```
CALL neptune.algo.vectors.topK.byEmbedding(
{
embedding: [0.1, 0.2, 0.3, ...],
topK: 3,
concurrency: 1
}
)
YIELD node, score
RETURN node, score
```
**Warning**
Using `MATCH (n)` or `WITH` as the prefix of `CALL neptune.algo.vectors.topK.byEmbedding` is forbidden. MATCH(n) can return a large number of nodes. Keep in mind that every node in (n) invokes a separate run of .vectors.topK.byEmbedding. Too many inputs can therefore result in very long runtimes and many outputs.
## Sample `.vectors.topKByEmbedding` output
Here is an example of the output returned by .vectors.topK.byEmbedding when run against the sample Wikipedia dataset using the following query:
```
aws neptune-graph execute-query \
--graph-identifier ${graphIdentifier} \
--query-string "CALL neptune.algo.vectors.topK.byEmbedding({ embedding: [*an embedding*], topK: 3 })
YIELD node, score
RETURN node, score"
--language open_cypher \
/tmp/out.txt
{
"results": [
{
"node": {
"~id": "0",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 0,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "The 24-hour clock is a way of telling the time in which the day runs from midnight to midnight and is divided into 24 hours\\, numbered from 0 to 23. It does not use a.m. or p.m. This system is also referred to (only in the US and the English speaking parts of Canada) as military time or (only in the United Kingdom and now very rarely) as continental time. In some parts of the world\\, it is called railway time. Also\\, the international standard notation of time (ISO 8601) is based on this format."
}
},
"score": 0.0
},
{
"node": {
"~id": "2",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 2,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "However\\, the US military prefers not to say 24:00 - they do not like to have two names for the same thing\\, so they always say \"23:59\"\\, which is one minute before midnight."
}
},
"score": 24.000200271606447
},
{
"node": {
"~id": "3",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 3,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "24-hour clock time is used in computers\\, military\\, public safety\\, and transport. In many Asian\\, European and Latin American countries people use it to write the time. Many European people use it in speaking."
}
},
"score": 25.013729095458986
}
]
}
```
# .vectors.topKByNode algorithm (deprecated)
The `.vectors.topKByNode` algorithm finds the `topK` nearest neighbors of a node based on the distance of their vector embeddings from the node.
## `.vectors.topKByNode` syntax
```
CALL neptune.algo.vectors.topKByNode(
[a list of one or more nodes (required)],
{
topK: the number of result nodes to return (optional, default: 10),
concurrency: the number of cores to use to run the algorithm (optional)
}
)
YIELD node, score
RETURN node, score
```
## `.vectors.topKByNode` input
+ **a list of one or more source nodes** *(required)* – *type:* `Node[]` or `NodeId[]`.
If the source-node list is empty then the query result is also empty.
+ **topK** *(optional)* *type:* a positive integer; *default:* 10.
The number of result nodes to return.
+ **concurrency** *(optional)* – *type:* 0 or 1; *default:* 0.
Controls the number of concurrent threads used to run the algorithm.
If set to `0`, uses all available threads to complete execution of the individual algorithm invocation. If set to `1`, uses a single thread. This can be useful when requiring the invocation of many algorithms concurrently.
## `.vectors.topKByNode` outputs
For each source node:
+ **source** – The source node.
+ **node** – A node whose embedding is at one of the `topK` nearest distances from the source node's embedding.
+ **score** – The distance between the source node's embedding and the embedding of the close node.
## `.vectors.topKByNode` query example
```
MATCH ( n:airport {code: 'ANC'} )
CALL neptune.algo.vectors.topKByNode(
n,
{
topK: 10,
concurrency: 1
}
)
YIELD node, score
RETURN n, node, score
```
**Warning**
In queries like the one above, be careful to limit `MATCH(n)` so that it doesn't return a large number of nodes. Keep in mind that every node in `n` invokes a separate run of `.vectors.topKByNode`. Too many inputs can therefore result in very long runtimes. Use `LIMIT` or put conditions on the `MATCH` clause to restrict its output appropriately.
## Sample `.vectors.topKByNode` output
Here is an example of the output returned by `.vectors.topKByNode` when run against the sample Wikipedia dataset using the following query:
```
aws neptune-graph execute-query \
--graph-identifier ${graphIdentifier} \
--query-string "MATCH ( n {`~id`: '0'} )
CALL neptune.algo.vectors.topKByNode(n, {topK: 3})
YIELD node, score
RETURN n, node, score" \
--language open_cypher \
/tmp/out.txt
{
"results": [
{
"n": {
"~id": "0",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 0,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "The 24-hour clock is a way of telling the time in which the day runs from midnight to midnight and is divided into 24 hours\\, numbered from 0 to 23. It does not use a.m. or p.m. This system is also referred to (only in the US and the English speaking parts of Canada) as military time or (only in the United Kingdom and now very rarely) as continental time. In some parts of the world\\, it is called railway time. Also\\, the international standard notation of time (ISO 8601) is based on this format."
}
},
"node": {
"~id": "0",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 0,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "The 24-hour clock is a way of telling the time in which the day runs from midnight to midnight and is divided into 24 hours\\, numbered from 0 to 23. It does not use a.m. or p.m. This system is also referred to (only in the US and the English speaking parts of Canada) as military time or (only in the United Kingdom and now very rarely) as continental time. In some parts of the world\\, it is called railway time. Also\\, the international standard notation of time (ISO 8601) is based on this format."
}
},
"score": 0.0
},
{
"n": {
"~id": "0",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 0,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "The 24-hour clock is a way of telling the time in which the day runs from midnight to midnight and is divided into 24 hours\\, numbered from 0 to 23. It does not use a.m. or p.m. This system is also referred to (only in the US and the English speaking parts of Canada) as military time or (only in the United Kingdom and now very rarely) as continental time. In some parts of the world\\, it is called railway time. Also\\, the international standard notation of time (ISO 8601) is based on this format."
}
},
"node": {
"~id": "2",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 2,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "However\\, the US military prefers not to say 24:00 - they do not like to have two names for the same thing\\, so they always say \"23:59\"\\, which is one minute before midnight."
}
},
"score": 24.000200271606447
},
{
"n": {
"~id": "0",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 0,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "The 24-hour clock is a way of telling the time in which the day runs from midnight to midnight and is divided into 24 hours\\, numbered from 0 to 23. It does not use a.m. or p.m. This system is also referred to (only in the US and the English speaking parts of Canada) as military time or (only in the United Kingdom and now very rarely) as continental time. In some parts of the world\\, it is called railway time. Also\\, the international standard notation of time (ISO 8601) is based on this format."
}
},
"node": {
"~id": "3",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 3,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "24-hour clock time is used in computers\\, military\\, public safety\\, and transport. In many Asian\\, European and Latin American countries people use it to write the time. Many European people use it in speaking."
}
},
"score": 25.013729095458986
}
]
}
```
# .vectors.topK.byNode algorithm
The `.vectors.topK.byNode` algorithm finds the `topK` nearest neighbors of a node based on the distance of their vector embeddings from the node.
## `.vectors.topK.byNode` syntax
```
CALL neptune.algo.vectors.topK.byNode(
[a list of one or more nodes (required)],
{
topK: the number of result nodes to return (optional, default: 10),
concurrency: the number of cores to use to run the algorithm (optional)
}
)
YIELD node, score
RETURN node, score
```
## `.vectors.topK.byNode` input
+ **a list of one or more source nodes** *(required)* – *type:* `Node[]` or `NodeId[]`.
If the source-node list is empty then the query result is also empty.
+ **topK** *(optional)* *type:* a positive integer; *default:* 10.
The number of result nodes to return.
+ **concurrency** *(optional)* – *type:* 0 or 1; *default:* 0.
Controls the number of concurrent threads used to run the algorithm.
If set to `0`, uses all available threads to complete execution of the individual algorithm invocation. If set to `1`, uses a single thread. This can be useful when requiring the invocation of many algorithms concurrently.
## `.vectors.topK.byNode` outputs
For each source node:
+ **source** – The source node.
+ **node** – A node whose embedding is at one of the `topK` nearest distances from the source node's embedding.
+ **score** – The squared Euclidean distance between the source node's embedding and the embedding of the close node.
## `.vectors.topK.byNode` query example
```
MATCH ( n:airport {code: 'ANC'} )
CALL neptune.algo.vectors.topK.byNode(
n,
{
topK: 10,
concurrency: 1
}
)
YIELD node, score
RETURN n, node, score
```
**Warning**
In queries like the one above, be careful to limit `MATCH(n)` so that it doesn't return a large number of nodes. Keep in mind that every node in `n` invokes a separate run of `.vectors.topK.byNode`. Too many inputs can therefore result in very long runtimes. Use `LIMIT` or put conditions on the `MATCH` clause to restrict its output appropriately.
## Sample `.vectors.topK.byNode` output
Here is an example of the output returned by `.vectors.topK.byNode` when run against the sample Wikipedia dataset using the following query:
```
aws neptune-graph execute-query \
--graph-identifier ${graphIdentifier} \
--query-string "MATCH ( n {`~id`: '0'} )
CALL neptune.algo.vectors.topK.byNode(n, {topK: 3})
YIELD node, score
RETURN n, node, score" \
--language open_cypher \
/tmp/out.txt
{
"results": [
{
"n": {
"~id": "0",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 0,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "The 24-hour clock is a way of telling the time in which the day runs from midnight to midnight and is divided into 24 hours\\, numbered from 0 to 23. It does not use a.m. or p.m. This system is also referred to (only in the US and the English speaking parts of Canada) as military time or (only in the United Kingdom and now very rarely) as continental time. In some parts of the world\\, it is called railway time. Also\\, the international standard notation of time (ISO 8601) is based on this format."
}
},
"node": {
"~id": "0",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 0,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "The 24-hour clock is a way of telling the time in which the day runs from midnight to midnight and is divided into 24 hours\\, numbered from 0 to 23. It does not use a.m. or p.m. This system is also referred to (only in the US and the English speaking parts of Canada) as military time or (only in the United Kingdom and now very rarely) as continental time. In some parts of the world\\, it is called railway time. Also\\, the international standard notation of time (ISO 8601) is based on this format."
}
},
"score": 0.0
},
{
"n": {
"~id": "0",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 0,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "The 24-hour clock is a way of telling the time in which the day runs from midnight to midnight and is divided into 24 hours\\, numbered from 0 to 23. It does not use a.m. or p.m. This system is also referred to (only in the US and the English speaking parts of Canada) as military time or (only in the United Kingdom and now very rarely) as continental time. In some parts of the world\\, it is called railway time. Also\\, the international standard notation of time (ISO 8601) is based on this format."
}
},
"node": {
"~id": "2",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 2,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "However\\, the US military prefers not to say 24:00 - they do not like to have two names for the same thing\\, so they always say \"23:59\"\\, which is one minute before midnight."
}
},
"score": 24.000200271606447
},
{
"n": {
"~id": "0",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 0,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "The 24-hour clock is a way of telling the time in which the day runs from midnight to midnight and is divided into 24 hours\\, numbered from 0 to 23. It does not use a.m. or p.m. This system is also referred to (only in the US and the English speaking parts of Canada) as military time or (only in the United Kingdom and now very rarely) as continental time. In some parts of the world\\, it is called railway time. Also\\, the international standard notation of time (ISO 8601) is based on this format."
}
},
"node": {
"~id": "3",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 3,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "24-hour clock time is used in computers\\, military\\, public safety\\, and transport. In many Asian\\, European and Latin American countries people use it to write the time. Many European people use it in speaking."
}
},
"score": 25.013729095458986
}
]
}
```
# .vectors.upsert algorithm
The `.vectors.upsert` algorithm is used to add a new embedding or update an existing one for a node.
**Important**
Updates to vector embeddings are not ACID compliant. For details and best practices to minimize inconsistencies, see [Vector index transaction support](vector-index.md#vector-index-transaction-support).
## `.vectors.upsert` syntax
```
CALL neptune.algo.vectors.upsert(
"a target node (required)",
[the embedding to upsert for the target node (required)]
)
YIELD node, embedding, success
RETURN node, embedding, success
```
## `.vectors.upsert` input
+ **a target node** *(required)* – *type:* `Node` or `NodeId`.
The node for which you want to upsert an embedding.
+ **an embedding** *(required)* – *type:* a list of floating-point values.
The embedding that you want to upsert for the target node.
If the node has an existing embedding, this must match the dimension of the existing one or an exception is thrown.
## `.vectors.upsert` outputs
If the target node already has an existing embedding then `.vectors.upsert` replaces it with the one supplied. Otherwise `.vectors.upsert` adds the supplied embedding for the target node.
+ **node** – The target node.
+ **embedding** – The embedding that was supplied to be upserted.
+ **success** – A Boolean value: `true` indicates that the upsert succeded, and `false` that it failed.
## `.vectors.upsert` query examples
```
CALL neptune.algo.vectors.upsert(
"person933",
[0.1, 0.2, 0.3, ..]
)
YIELD node, embedding, success
RETURN node, embedding, success
```
```
UNWIND [
{id: "933", embedding: [1,2,3,4]},
{id: "934", embedding: [-1,-2,-3,-4]}
] as entry
MATCH (n:person) WHERE id(n)=entry.id WITH n, entry.embedding as embedding
CALL neptune.algo.vectors.upsert(n, embedding)
YIELD success
RETURN n, embedding, success
```
## Sample `.vectors.upsert` output
Here is an example of the output returned by `.vectors.upsert` when run against the sample Wikipedia dataset using the following query:
```
aws neptune-graph execute-query \
--graph-identifier ${graphIdentifier} \
--query-string "MATCH (n{\`~id\`:\"0\"})
CALL neptune.algo.vectors.get(n)
YIELD embedding AS vector
MATCH (m{`~id`: '1'})
CALL neptune.algo.vectors.upsert(m, vector)
YIELD node, embedding, success
RETURN node, embedding, success"
--language open_cypher \
/tmp/out.txt
{
"results": [
{
"node": {
"~id": "1",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 1,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "A time in the 24-hour clock is written in the form hours:minutes (for example\\, 01:23)\\, or hours:minutes:seconds (01:23:45). Numbers under 10 have a zero in front (called a leading zero); e.g. 09:07. Under the 24-hour clock system\\, the day begins at midnight\\, 00:00\\, and the last minute of the day begins at 23:59 and ends at 24:00\\, which is identical to 00:00 of the following day. 12:00 can only be mid-day. Midnight is called 24:00 and is used to mean the end of the day and 00:00 is used to mean the beginning of the day. For example\\, you would say \"Tuesday at 24:00\" and \"Wednesday at 00:00\" to mean exactly the same time."
}
},
"embedding": [
0.07711287587881088,
0.3197174072265625,
-0.2051590085029602,
0.6302579045295715,
0.032093219459056857,
0.200703963637352,
0.16665680706501008,
-0.31295087933540347,
0.17575109004974366,
0.5308129191398621,
-0.37528499960899355,
0.3338659405708313,
-0.046272162348032,
0.07841536402702332,
-0.3490406274795532,
0.27182886004447939,
0.3073517680168152,
-0.08306130766868592,
0.5035958886146545,
0.254621684551239,
-0.40407684445381167,
0.28878292441368105,
-0.22588828206062318,
-0.13185778260231019,
-0.21559733152389527,
0.4900434613227844,
0.03866531699895859,
0.507415771484375,
-0.3067346513271332,
0.10740984976291657,
0.08998646587133408,
-0.2652775049209595,
-0.28492602705955508,
0.33600345253944399,
-0.27227747440338137,
0.3691731095314026,
-0.2815995514392853,
0.0856710895895958,
-0.13187488913536073,
0.4753035008907318,
-0.2241700142621994,
0.20263174176216126,
0.4390721619129181,
0.06424559652805329,
0.2463042289018631,
-0.39631763100624087,
0.2971232533454895,
0.2415716052055359,
-0.02803819440305233,
0.32105034589767458,
-0.02222033031284809,
-0.008510420098900795,
-0.00032598740654066205,
0.031057516112923623,
-0.5332233309745789,
0.45022767782211306,
-0.6829474568367004,
1.3313145637512208,
0.19445496797561646,
-0.15697629749774934,
-0.09996363520622254,
-0.2786232829093933,
-0.09833164513111115,
-0.17644722759723664,
0.11717787384986878,
0.2820119559764862,
0.029635537415742875,
0.5247654914855957,
0.5323811173439026,
-0.06254086643457413,
-0.05274389684200287,
0.3877565860748291,
0.43260684609413149,
0.5207982063293457,
-0.27160540223121645,
-0.06000519543886185,
-0.032806672155857089,
-0.3594319522380829,
0.4218965470790863,
-0.3766363263130188,
0.44727250933647158,
-0.04586323723196983,
0.06902860850095749,
0.3030509352684021,
0.18945887684822083,
0.21681705117225648,
-0.014492596499621868,
-0.38649576902389529,
-0.1129651814699173,
0.050081491470336917,
-0.01697717048227787,
0.1415158063173294,
-0.3284287750720978,
-0.02309800498187542,
-0.2051207274198532,
-0.017861712723970414,
-0.07372242212295532,
-0.12263767421245575,
0.21828559041023255,
-0.36898064613342287,
0.3558262288570404,
-0.16924124956130982,
-0.31757786870002749,
0.5452765226364136,
0.24666202068328858,
-0.08289600908756256,
-0.14674079418182374,
-0.18049933016300202,
0.3646247982978821,
0.42489132285118105,
0.0909421369433403,
-0.1764664500951767,
0.22471413016319276,
0.049531541764736179,
-0.022898104041814805,
0.08607156574726105,
0.14532636106014253,
-0.205774188041687,
-0.3457978069782257,
-1.2771626710891724,
0.2826114892959595,
0.2066900134086609,
-0.3884444832801819,
-0.3564482629299164,
-0.25118574500083926,
-0.728326141834259,
0.5217206478118897,
-0.43305152654647829,
0.3510914444923401,
0.5106240510940552,
-0.11594267934560776,
0.43993058800697329,
0.25412991642951968,
0.4275965392589569,
0.1463870108127594,
0.3510439395904541,
0.1619710624217987,
0.11160195618867874,
-0.22760489583015443,
-0.23652249574661256,
0.05374380201101303,
0.7251803278923035,
-0.13991153240203858,
0.9363659024238586,
-0.05858418717980385,
0.5233941674232483,
0.12388131022453308,
0.6248424649238586,
-0.11751417070627213,
0.09689709544181824,
0.7467237710952759,
0.2247271090745926,
-0.6747357845306397,
-0.16039365530014039,
-0.41555172204971316,
-0.04566565155982971,
0.21260707080364228,
0.2549103796482086,
0.24795542657375337,
0.5625612735748291,
0.8036459684371948,
0.15800043940544129,
0.04797195643186569,
-0.15839435160160066,
-0.06506697088479996,
-0.2577322721481323,
0.3262946903705597,
0.5458049178123474,
0.616370439529419,
-0.35092639923095705,
0.048758912831544879,
0.11522434651851654,
0.04175107553601265,
-0.12269306182861328,
0.1227836161851883,
0.4020257890224457,
0.07093577086925507,
-0.1880340874195099,
0.5334663391113281,
0.46888044476509097,
0.18104688823223115,
0.30756646394729617,
0.29316428303718569,
-0.10604366660118103,
0.44999250769615176,
0.18227706849575044,
0.5962150692939758,
0.38278165459632876,
-0.40461188554763796,
0.17775404453277589,
-0.16349074244499207,
0.06950787454843521,
0.7547341585159302,
-0.4842711389064789,
0.4062837064266205,
0.09000574052333832,
0.03859427571296692,
0.24143263697624207,
-0.3383118510246277,
0.3363209366798401,
0.10778547078371048,
0.3429640233516693,
-0.20395530760288239,
0.011477324180305004,
0.6145590543746948,
-0.5488739609718323,
-0.26194247603416445,
-0.09723474085330963,
-0.19020821154117585,
-0.18068274855613709,
0.1601778119802475,
0.038950759917497638,
0.6372026205062866,
-0.12897184491157533,
0.10720998793840409,
0.13482464849948884,
-0.07540713250637055,
-0.0881727784872055,
0.5626690983772278,
-0.31975486874580386,
-0.029084375128149987,
0.43618619441986086,
0.32975345849990847,
-0.4053913652896881,
0.15788795053958894,
-0.3212168216705322,
-0.20272433757781983,
-0.8973743319511414,
0.060059018433094028,
-0.014103145338594914,
-0.3387225568294525,
-0.49839726090431216,
-0.011007139459252358,
-0.16101065278053285,
-0.20850643515586854,
0.4891682267189026,
0.33551496267318728,
-0.23595896363258363,
-0.4257577359676361,
-0.48884832859039309,
0.48760101199150088,
0.34031161665916445,
0.1722799688577652,
-0.35575979948043826,
0.629051923751831,
-0.8014369010925293,
0.575096607208252,
0.421142578125,
-0.2668846547603607,
-0.046029768884181979,
0.2791147530078888,
-0.22112232446670533,
0.02008579671382904,
0.22087614238262177,
-0.17961964011192323,
0.4235396981239319,
0.295818567276001,
-0.18260923027992249,
0.3227207660675049,
0.11412205547094345,
0.04591478034853935,
0.5127033591270447,
0.428005576133728,
0.20718106627464295,
0.18405631184577943,
-0.22416146099567414,
0.4277373254299164,
0.5384698510169983,
0.04109276458621025,
0.5105301141738892,
0.473961740732193,
-0.6853302717208862,
-0.16557902097702027,
-0.12704522907733918,
0.0026600745040923359,
0.5272349715232849,
0.12121742218732834,
0.427141010761261,
-0.3047095239162445,
0.5948843359947205,
0.335798442363739,
0.35749775171279909,
-0.18497343361377717,
0.26501506567001345,
0.1564970314502716,
0.4210122525691986,
-0.1915784478187561,
0.057152874767780307,
-0.28498271107673647,
0.04969947412610054,
0.7697478532791138,
0.5546697974205017,
0.0958070456981659,
-0.3533228933811188,
0.4784282147884369,
0.624963104724884,
0.2151053100824356,
0.17361000180244447,
0.22527147829532624,
-0.12481484562158585,
0.4212929904460907,
-0.2926572859287262,
0.2562543749809265,
0.38751208782196047,
0.1340814083814621,
0.0680900365114212,
0.2952287793159485,
0.12217980623245239,
-0.2869758605957031,
0.15682946145534516,
-0.022066200152039529,
-0.09002991020679474,
-0.2826828360557556,
0.84619140625,
0.7544476985931397,
0.5953861474990845,
0.6517565250396729,
-0.07932830601930618,
0.22802823781967164,
-0.135965958237648,
-0.8263510465621948,
-0.6325801610946655,
-0.5928561091423035,
0.4108763635158539,
0.0964483916759491,
-0.5045000910758972,
-0.06772734969854355,
-0.79107666015625,
0.060380879789590839,
0.015578197315335274,
0.32540079951286318,
-0.044692762196063998,
-0.17132098972797395,
-0.19123415648937226,
0.17911623418331147,
0.3269428014755249,
-0.22874118387699128,
0.4686919152736664,
-0.15749554336071015,
-0.25185921788215639,
-0.21561351418495179,
-0.10132477432489395,
-0.057977184653282168,
0.09759098291397095,
0.16202516853809358,
0.01888692006468773,
0.1724688857793808,
-0.3449697196483612,
0.4449881315231323,
0.10185430943965912,
-0.2976726293563843,
0.06075461208820343,
0.21909406781196595,
-0.07409229874610901,
0.6881160140037537,
0.17447273433208466,
-0.048471711575984958,
0.5318611264228821,
0.30954766273498537,
-0.24350836873054505,
0.14386573433876038,
-0.10827953368425369,
0.08575868606567383,
0.14200334250926972,
0.5095603466033936,
-0.025056177750229837,
0.24901045858860017,
-0.23696841299533845,
-0.03630203381180763,
0.45206722617149355,
0.5019969344139099,
-0.21705971658229829,
-0.08452687412500382,
-0.10376924276351929,
-0.3200875520706177,
-0.2048267275094986,
-0.2703971266746521,
0.2925371825695038,
0.3755778670310974,
0.2522588074207306,
0.22964833676815034,
0.7995960116386414,
0.12206973880529404,
0.2896155118942261,
0.04163726791739464,
-0.12602514028549195,
0.004978220444172621,
0.3399927020072937,
0.09124521911144257,
-0.5452605485916138,
0.2247130423784256,
0.23503662645816804,
0.06750215590000153,
-0.2884872257709503,
-0.2791622579097748,
-0.1780446618795395,
-0.44350507855415347,
-0.1840016394853592,
0.8970789909362793,
-0.3687478303909302,
0.36603569984436037,
0.23560358583927155,
0.020292289555072786,
0.2446030080318451,
4.3314642906188969,
0.194863960146904,
-0.10218192636966706,
0.5695234537124634,
0.016988292336463929,
-0.15768325328826905,
0.050476688891649249,
0.09948820620775223,
-0.06554386019706726,
0.22301962971687318,
-0.05468735471367836,
0.29051196575164797,
0.12100572139024735,
0.4127441644668579,
0.1667146235704422,
0.0587792843580246,
-0.09758614003658295,
-0.20510408282279969,
-0.21746976673603059,
0.43335747718811037,
-0.32159093022346499,
0.6942153573036194,
0.6173154711723328,
0.3104712665081024,
0.5751503109931946,
0.4174514412879944,
-0.2948107421398163,
0.3532458245754242,
0.4869029223918915,
0.3115881681442261,
0.28135108947753909,
0.38450825214385989,
0.016915690153837205,
-0.11598393321037293,
-0.32250434160232546,
-0.06988134980201721,
0.22417351603507996,
-0.35582518577575686,
0.2677224576473236,
0.008019124157726765,
-0.19177919626235963,
0.5731900334358215,
-0.03540642186999321,
0.43302130699157717,
0.1796148121356964,
-0.005056577268987894,
0.37953320145606997,
0.13488957285881043,
0.7240068912506104,
-0.3088097870349884,
0.5610846281051636,
-0.29582735896110537,
-0.20909856259822846,
-0.2881403863430023,
0.10329002141952515,
0.49255961179733279,
0.14558906853199006,
0.41020694375038149,
0.04002099484205246,
-0.24476903676986695,
-0.389543354511261,
0.3901459574699402,
0.6170359253883362,
0.18917717039585114,
-0.41235554218292239,
-0.19313344359397889,
-0.10294703394174576,
0.5560699105262756,
0.5773581266403198,
-0.17282086610794068,
0.28679269552230837,
0.34322652220726015,
-0.07227988541126251,
-0.5244243741035461,
-0.26529040932655337,
-0.11131077259778977,
-0.19524210691452027,
0.4082769453525543,
-0.009217939339578152,
-0.1462743580341339,
0.7264918684959412,
-0.09149657934904099,
-0.3374916911125183,
-0.05742226541042328,
-0.3913151025772095,
0.7185215950012207,
-0.3785516619682312,
-0.00010882654169108719,
0.6655824780464172,
0.4194306433200836,
0.3726831376552582,
-0.014721312560141087,
0.5345744490623474,
0.33022087812423708,
-0.06344814598560333,
-0.1560882031917572,
0.22698232531547547,
-3.8697707653045656,
0.06812435388565064,
-0.4368731677532196,
-0.07041455805301666,
-0.015291529707610608,
-0.41140303015708926,
0.31612321734428408,
0.2914712429046631,
-0.3867192566394806,
-0.026363473385572435,
-0.08788029104471207,
-0.10701339691877365,
-0.2673511505126953,
0.27538666129112246,
-0.3661351501941681,
0.5879861116409302,
0.06352981925010681,
0.15547777712345124,
0.0863194614648819,
-0.021183960139751436,
0.428565114736557,
0.04859453812241554,
0.35721391439437868,
-0.3864029347896576,
-0.20986808836460114,
0.15433000028133393,
0.25567296147346499,
0.25359275937080386,
-0.4783596396446228,
-0.010366495698690415,
0.4777776598930359,
-0.029405448585748674,
0.3631121814250946,
-0.18738743662834168,
0.2193489819765091,
0.7861229777336121,
-0.01961355283856392,
0.16653983294963838,
-0.4193624258041382,
0.3085209131240845,
-0.03517897054553032,
-0.035910699516534808,
0.37241387367248537,
-0.13769084215164185,
-0.08015040308237076,
0.4384872615337372,
-0.12396809458732605,
0.15661391615867616,
-0.3919837176799774,
-0.6586825251579285,
0.5687432885169983,
0.0396936871111393,
-0.09660491347312927,
0.05788198113441467,
0.48911261558532717,
0.5213083028793335,
0.3355415165424347,
-0.006735790055245161,
-0.11381038278341294,
0.09182903915643692,
-0.11055094748735428,
-0.28275448083877566,
0.24975340068340302,
0.11746659129858017,
-0.42452141642570498,
-0.2323901206254959,
-0.38694220781326296,
0.015501483343541623,
0.6440262198448181,
-0.3121536672115326,
-0.08778296411037445,
-0.14549347758293153,
0.01749151013791561,
-0.5398207902908325,
0.4124368131160736,
0.5154116749763489,
-0.34769660234451296,
0.5662841796875,
0.4989481270313263,
0.06761053949594498,
0.014184223487973214,
0.601079523563385,
-0.3859538435935974,
0.3446619212627411,
2.190366744995117,
0.4051366150379181,
2.288928508758545,
0.5293960571289063,
-0.3505767583847046,
0.5397417545318604,
-0.6520821452140808,
0.4239364266395569,
0.2618080675601959,
0.20174439251422883,
0.030146604403853418,
0.0610184520483017,
0.062213074415922168,
-0.11276254057884217,
-0.1301877349615097,
-0.19404706358909608,
0.5268515348434448,
-0.7370991706848145,
0.028712594881653787,
-0.4024544954299927,
0.18225152790546418,
0.7267741560935974,
-0.2734072208404541,
0.1759040206670761,
-0.2950340211391449,
0.14166314899921418,
0.6515365242958069,
-0.29643580317497256,
-0.06734377890825272,
0.09662584215402603,
-0.010966300964355469,
-0.3204823136329651,
0.6417866349220276,
-0.051218003034591678,
-0.008819818496704102,
0.5098630785942078,
-0.21459998190402986,
4.437846660614014,
-0.24779054522514344,
0.018799694254994394,
-0.01747281290590763,
-0.0487254373729229,
0.6121163964271545,
0.4686623811721802,
-0.22926479578018189,
-0.03692511469125748,
-0.4286654591560364,
0.46073317527770998,
0.16875289380550385,
-0.014255600981414318,
-0.07684683054685593,
0.12223237752914429,
-0.30599895119667055,
0.39215049147605898,
0.22453786432743073,
0.5624862313270569,
-0.011985340155661106,
0.05180392041802406,
0.030400553718209268,
0.08391892164945603,
0.10214067250490189,
-0.4449590742588043,
0.2225639522075653,
0.3862999975681305,
0.24732927978038789,
-0.05571140721440315,
-0.021564822643995286,
0.28468334674835207,
5.213898658752441,
0.13289497792720796,
-0.1400047093629837,
-0.39865049719810488,
0.12139834463596344,
0.45539018511772158,
-0.1865275651216507,
-0.08270177245140076,
-0.38520801067352297,
0.08869948983192444,
-0.05266271159052849,
0.14364486932754517,
-0.2860695719718933,
0.4430652856826782,
0.7777798771858215,
0.21114271879196168,
-0.358752578496933,
-0.3664247989654541,
0.6665846109390259,
-0.40493687987327578,
0.1747705042362213,
-0.06670021265745163,
0.20972059667110444,
-0.19101694226264954,
0.23892535269260407,
-0.08149895817041397,
0.018510373309254648,
0.8112999796867371,
0.07871513813734055,
0.09570053964853287,
0.5030911564826965,
0.21463628113269807,
-0.31457462906837466,
0.3051794767379761,
-0.39506298303604128,
0.06605447828769684,
0.6144300699234009,
-0.4566810429096222,
0.3146623373031616,
0.1887989640235901,
0.9544244408607483,
0.5103438496589661,
-0.4859951138496399,
-0.32647767663002016,
-0.07584235072135925,
0.21474787592887879,
-0.1920636147260666,
-0.4472030997276306,
0.08618132770061493,
-0.17384092509746552,
-0.20969024300575257,
-0.1831870973110199,
0.8782939314842224,
-0.15720084309577943,
0.37347128987312319,
0.5088165998458862,
0.29395583271980288,
-0.3580363988876343,
-0.17590023577213288,
-0.508141279220581,
0.4661521315574646,
0.142064169049263,
-0.05615571141242981,
0.592810869216919,
0.37807324528694155,
-0.14052101969718934,
-0.19951890408992768,
-0.12800109386444093,
0.748070478439331,
0.13753947615623475,
-0.08446942269802094,
0.3747580945491791,
-0.12847286462783814,
-0.13892321288585664,
0.08525972813367844,
0.12516680359840394,
0.5701874494552612,
-0.24708901345729829,
0.0679594948887825,
0.10870008915662766,
0.20561885833740235,
-0.7872452139854431,
0.07303950190544129,
0.35694700479507449,
0.245212584733963,
0.3299793303012848,
-0.010669616051018238,
-0.12047348916530609,
0.3540535271167755,
0.32180890440940859,
0.3066200911998749,
0.021576205268502237,
0.17679384350776673,
-0.23050960898399354,
0.1292697787284851,
0.022921407595276834,
0.5460971593856812,
0.3612038493156433,
0.1963733434677124,
0.4622957706451416,
0.16855642199516297,
0.2564740478992462,
-0.27637141942977908,
-0.16345584392547608,
0.08119463175535202,
0.07851938903331757,
-0.5181471109390259,
-0.5290305614471436,
0.5271350741386414,
0.3391841650009155,
0.501441240310669,
0.740936279296875,
-0.26713573932647707,
0.030347898602485658,
0.05174243822693825
],
"success": true
}
]
}
```
# .vectors.remove algorithm
The `.vectors.remove` algorithm is used to remove the embedding from a node.
**Important**
Updates to vector embeddings are not ACID compliant. For details and best practices to minimize inconsistencies, see [Vector index transaction support](vector-index.md#vector-index-transaction-support).
## `.vectors.remove` syntax
```
CALL neptune.algo.vectors.remove(
[a list of one or more nodes]
)
YIELD node, success
RETURN node, success
```
## `.vectors.remove` input
+ **a target node list** *(required)* – *type:* `Node[]` or `NodeId[]`.
The node(s) from which you want to remove the embedding. If an empty list is supplied, the result will be empty.
## `.vectors.remove` outputs
The following outputs are returned for each target node, and if the node has an embedding, the embedding is removed:
+ **node** – The target node.
+ **success** – A Boolean value: `true` indicates that the removal succeded for the node, and `false` indicates that it failed.
## `.vectors.remove` query examples
```
CALL neptune.algo.vectors.remove( ["person933"] )
YIELD node, success
RETURN node, success
```
```
MATCH (n: Student)
CALL neptune.algo.vectors.remove(n)
YIELD status
RETURN n, success
```
## Sample `.vectors.remove` output
Here is an example of the output returned by `.vectors.remove` when run against the sample Wikipedia dataset using the following query:
```
aws neptune-graph execute-query \
--graph-identifier ${graphIdentifier} \
--query-string "MATCH (n {`~id`: '1'})
CALL neptune.algo.vectors.remove(n)
YIELD node, success
RETURN node, success" \
--language open_cypher \
/tmp/out.txt
{
"results": [
{
"node": {
"~id": "1",
"~entityType": "node",
"~labels": [],
"~properties": {
"title": "24-hour clock",
"views": 2450.62548828125,
"wiki_id": 9985,
"paragraph_id": 1,
"url": "https://simple.wikipedia.org/wiki?curid=9985",
"langs": 30,
"text": "A time in the 24-hour clock is written in the form hours:minutes (for example\\, 01:23)\\, or hours:minutes:seconds (01:23:45). Numbers under 10 have a zero in front (called a leading zero); e.g. 09:07. Under the 24-hour clock system\\, the day begins at midnight\\, 00:00\\, and the last minute of the day begins at 23:59 and ends at 24:00\\, which is identical to 00:00 of the following day. 12:00 can only be mid-day. Midnight is called 24:00 and is used to mean the end of the day and 00:00 is used to mean the beginning of the day. For example\\, you would say \"Tuesday at 24:00\" and \"Wednesday at 00:00\" to mean exactly the same time."
}
},
"success": true
}
]
}
```