Fixes #4090: The apoc.vectordb.*.get/query procedures should search f…

…or nodes/relationships with mapping config (#4092) * Fixes #4090: The apoc.vectordb.*.get/query procedures should search for nodes/relationships with mapping config * changed create mode from boolean to enum
neo4j-contrib · May 29, 2024 · ba47c81 · ba47c81
1 parent 368d62e
commit ba47c81
Show file tree

Hide file tree

Showing 19 changed files with 408 additions and 228 deletions.
diff --git a/docs/asciidoc/modules/ROOT/pages/database-integration/vectordb/chroma.adoc b/docs/asciidoc/modules/ROOT/pages/database-integration/vectordb/chroma.adoc
@@ -119,17 +119,6 @@ CALL apoc.vectordb.chroma.queryAndUpdate($host,
 | ...
 |===
 
-[NOTE]
-====
-We can use mapping with `apoc.vectordb.chroma.getAndUpdate` procedure as well
-====
-
-[NOTE]
-====
-To optimize performances, we can choose what to `YIELD` with the apoc.vectordb.chroma.query and the `apoc.vectordb.chroma.get` procedures.
-For example, by executing a `CALL apoc.vectordb.chroma.query(...) YIELD metadata, score, id`, the RestAPI request will have an {"include": ["metadatas", "documents", "distances"]},
-so that we do not return the other values that we do not need.
-====
 
 We can define a mapping, to fetch the associated nodes and relationships and optionally create them, by leveraging the vector metadata.
 
@@ -157,7 +146,7 @@ which will be returned in the `entity` column result.
 
 
 
-Or else, we can create a node if not exists, via `create: true`:
+We can also set the mapping configuration `mode` to `CREATE_IF_MISSING` (which creates nodes if not exist), `READ_ONLY` (to search for nodes/rels, without making updates) or `UPDATE_EXISTING` (default behavior):
 
 [source,cypher]
 ----
@@ -166,7 +155,7 @@ CALL apoc.vectordb.chroma.queryAndUpdate($host, '<collection_id>',
     {},
     5, 
     { mapping: {
-            create: true,
+            mode: "CREATE_IF_MISSING",
             embeddingKey: "vect", 
             nodeLabel: "Test", 
             entityKey: "myId", 
@@ -200,6 +189,38 @@ and `()-[:TEST {myId: 'two', city: 'London', vect: [vector2]}]-()`,
 which will be returned in the `entity` column result.
 
 
+We can also use mapping for `apoc.vectordb.chroma.query` procedure, to search for nodes/rels fitting label/type and metadataKey, without making updates
+(i.e. equivalent to `*.queryOrUpdate` procedure with mapping config having `mode: "READ_ONLY"`).
+
+For example, with the previous relationships, we can execute the following procedure, which just return the relationships in the column `rel`:
+
+[source,cypher]
+----
+CALL apoc.vectordb.weaviate.query($host, 'test_collection',
+    [0.2, 0.1, 0.9, 0.7],
+    {},
+    5, 
+    { fields: ["city", "foo"],
+      mapping: {
+        relType: "TEST", 
+        entityKey: "myId", 
+        metadataKey: "foo" 
+      }
+    })
+----
+
+[NOTE]
+====
+We can use mapping with `apoc.vectordb.chroma.get*` procedures as well
+====
+
+[NOTE]
+====
+To optimize performances, we can choose what to `YIELD` with the apoc.vectordb.chroma.query and the `apoc.vectordb.chroma.get` procedures.
+For example, by executing a `CALL apoc.vectordb.chroma.query(...) YIELD metadata, score, id`, the RestAPI request will have an {"include": ["metadatas", "documents", "distances"]},
+so that we do not return the other values that we do not need.
+====
+
 .Delete vectors (it leverages https://docs.trychroma.com/usage-guide#deleting-data-from-a-collection[this API])
 [source,cypher]
 ----

diff --git a/docs/asciidoc/modules/ROOT/pages/database-integration/vectordb/milvus.adoc b/docs/asciidoc/modules/ROOT/pages/database-integration/vectordb/milvus.adoc
@@ -147,7 +147,7 @@ which populates the two nodes as: `(:Test {myId: 'one', city: 'Berlin', vect: [v
 which will be returned in the `entity` column result.
 
 
-Or else, we can create a node if not exists, via `create: true`:
+We can also set the mapping configuration `mode` to `CREATE_IF_MISSING` (which creates nodes if not exist), `READ_ONLY` (to search for nodes/rels, without making updates) or `UPDATE_EXISTING` (default behavior):
 
 [source,cypher]
 ----
@@ -156,7 +156,7 @@ CALL apoc.vectordb.milvus.queryAndUpdate('http://localhost:19531', 'test_collect
     {},
     5, 
     { mapping: {
-            create: true,
+            mode: "CREATE_IF_MISSING",
             embeddingKey: "vect", 
             nodeLabel: "Test", 
             entityKey: "myId", 
@@ -189,9 +189,30 @@ which populates the two relationships as: `()-[:TEST {myId: 'one', city: 'Berlin
 and `()-[:TEST {myId: 'two', city: 'London', vect: [vector2]}]-()`,
 which will be returned in the `entity` column result.
 
+
+We can also use mapping for `apoc.vectordb.milvus.query` procedure, to search for nodes/rels fitting label/type and metadataKey, without making updates
+(i.e. equivalent to `*.queryOrUpdate` procedure with mapping config having `mode: "READ_ONLY"`).
+
+For example, with the previous relationships, we can execute the following procedure, which just return the relationships in the column `rel`:
+
+[source,cypher]
+----
+CALL apoc.vectordb.milvus.query('http://localhost:19531', 'test_collection',
+    [0.2, 0.1, 0.9, 0.7],
+    {},
+    5, 
+    { mapping: {
+            embeddingKey: "vect", 
+            relType: "TEST", 
+            entityKey: "myId", 
+            metadataKey: "foo" 
+        }
+    })
+----
+
 [NOTE]
 ====
-We can use mapping with `apoc.vectordb.milvus.getAndUpdate` procedure as well
+We can use mapping with `apoc.vectordb.milvus.get*` procedures as well
 ====
 
 [NOTE]

diff --git a/docs/asciidoc/modules/ROOT/pages/database-integration/vectordb/pinecone.adoc b/docs/asciidoc/modules/ROOT/pages/database-integration/vectordb/pinecone.adoc
@@ -161,7 +161,7 @@ which populates the two nodes as: `(:Test {myId: 'one', city: 'Berlin', vect: [v
 which will be returned in the `entity` column result.
 
 
-Or else, we can create a node if not exists, via `create: true`:
+We can also set the mapping configuration `mode` to `CREATE_IF_MISSING` (which creates nodes if not exist), `READ_ONLY` (to search for nodes/rels, without making updates) or `UPDATE_EXISTING` (default behavior):
 
 [source,cypher]
 ----
@@ -170,7 +170,7 @@ CALL apoc.vectordb.pinecone.queryAndUpdate($host, 'test-index',
     {},
     5, 
     { mapping: {
-            create: true,
+            mode: "CREATE_IF_MISSING",
             embeddingKey: "vect", 
             nodeLabel: "Test", 
             entityKey: "myId", 
@@ -203,9 +203,30 @@ which populates the two relationships as: `()-[:TEST {myId: 'one', city: 'Berlin
 and `()-[:TEST {myId: 'two', city: 'London', vect: [vector2]}]-()`,
 which will be returned in the `entity` column result.
 
+
+We can also use mapping for `apoc.vectordb.pinecone.query` procedure, to search for nodes/rels fitting label/type and metadataKey, without making updates
+(i.e. equivalent to `*.queryOrUpdate` procedure with mapping config having `mode: "READ_ONLY"`).
+
+For example, with the previous relationships, we can execute the following procedure, which just return the relationships in the column `rel`:
+
+[source,cypher]
+----
+CALL apoc.vectordb.pinecone.query($host, 'test-index',
+    [0.2, 0.1, 0.9, 0.7],
+    {},
+    5, 
+    { mapping: {
+            embeddingKey: "vect", 
+            relType: "TEST", 
+            entityKey: "myId", 
+            metadataKey: "foo" 
+        }
+    })
+----
+
 [NOTE]
 ====
-We can use mapping with `apoc.vectordb.pinecone.getAndUpdate` procedure as well
+We can use mapping with `apoc.vectordb.pinecone.get*` procedures as well
 ====
 
 [NOTE]

diff --git a/docs/asciidoc/modules/ROOT/pages/database-integration/vectordb/qdrant.adoc b/docs/asciidoc/modules/ROOT/pages/database-integration/vectordb/qdrant.adoc
@@ -149,7 +149,7 @@ which populates the two nodes as: `(:Test {myId: 'one', city: 'Berlin', vect: [v
 which will be returned in the `entity` column result.
 
 
-Or else, we can create a node if not exists, via `create: true`:
+We can also set the mapping configuration `mode` to `CREATE_IF_MISSING` (which creates nodes if not exist), `READ_ONLY` (to search for nodes/rels, without making updates) or `UPDATE_EXISTING` (default behavior):
 
 [source,cypher]
 ----
@@ -158,7 +158,7 @@ CALL apoc.vectordb.qdrant.queryAndUpdate($hostOrKey, 'test_collection',
     {},
     5, 
     { mapping: {
-            create: true,
+            mode: "CREATE_IF_MISSING",
             embeddingKey: "vect", 
             nodeLabel: "Test", 
             entityKey: "myId", 
@@ -191,9 +191,29 @@ which populates the two relationships as: `()-[:TEST {myId: 'one', city: 'Berlin
 and `()-[:TEST {myId: 'two', city: 'London', vect: [vector2]}]-()`,
 which will be returned in the `entity` column result.
 
+
+We can also use mapping for `apoc.vectordb.qdrant.query` procedure, to search for nodes/rels fitting label/type and metadataKey, without making updates
+(i.e. equivalent to `*.queryOrUpdate` procedure with mapping config having `mode: "READ_ONLY"`).
+
+For example, with the previous relationships, we can execute the following procedure, which just return the relationships in the column `rel`:
+
+[source,cypher]
+----
+CALL apoc.vectordb.qdrant.query($hostOrKey, 'test_collection',
+    [0.2, 0.1, 0.9, 0.7],
+    {},
+    5, 
+    { mapping: {
+            relType: "TEST", 
+            entityKey: "myId", 
+            metadataKey: "foo" 
+        }
+    })
+----
+
 [NOTE]
 ====
-We can use mapping with `apoc.vectordb.qdrant.getAndUpdate` procedure as well
+We can use mapping with `apoc.vectordb.qdrant.get*` procedures as well
 ====
 
 [NOTE]

diff --git a/docs/asciidoc/modules/ROOT/pages/database-integration/vectordb/weaviate.adoc b/docs/asciidoc/modules/ROOT/pages/database-integration/vectordb/weaviate.adoc
@@ -160,7 +160,7 @@ and `(:Test {myId: 'two', city: 'London', vect: [vector2]})`,
 which will be returned in the `entity` column result.
 
 
-Or else, we can create a node if not exists, via `create: true`:
+We can also set the mapping configuration `mode` to `CREATE_IF_MISSING` (which creates nodes if not exist), `READ_ONLY` (to search for nodes/rels, without making updates) or `UPDATE_EXISTING` (default behavior):
 
 [source,cypher]
 ----
@@ -170,7 +170,7 @@ CALL apoc.vectordb.weaviate.queryAndUpdate($host, 'test_collection',
     5, 
     { fields: ["city", "foo"],
       mapping: {
-        create: true,
+        mode: "CREATE_IF_MISSING",
         embeddingKey: "vect", 
         nodeLabel: "Test", 
         entityKey: "myId", 
@@ -205,9 +205,31 @@ and `()-[:TEST {myId: 'two', city: 'London', vect: [vector2]}]-()`,
 which will be returned in the `entity` column result.
 
 
+We can also use mapping for `apoc.vectordb.weaviate.query` procedure, to search for nodes/rels fitting label/type and metadataKey, without making updates
+(i.e. equivalent to `*.queryOrUpdate` procedure with mapping config having `mode: "READ_ONLY"`).
+
+For example, with the previous relationships, we can execute the following procedure, which just return the relationships in the column `rel`:
+
+[source,cypher]
+----
+CALL apoc.vectordb.weaviate.query($host, 'test_collection',
+    [0.2, 0.1, 0.9, 0.7],
+    {},
+    5, 
+    { fields: ["city", "foo"],
+      mapping: {
+        relType: "TEST", 
+        entityKey: "myId", 
+        metadataKey: "foo" 
+      }
+    })
+----
+
+
+
 [NOTE]
 ====
-We can use mapping with `apoc.vectordb.weaviate.getAndUpdate` procedure as well
+We can use mapping with `apoc.vectordb.weaviate.get*` procedures as well
 ====
 
 [NOTE]

diff --git a/extended-it/src/test/java/apoc/vectordb/ChromaDbTest.java b/extended-it/src/test/java/apoc/vectordb/ChromaDbTest.java
@@ -1,8 +1,6 @@
 package apoc.vectordb;
 
 import apoc.util.TestUtil;
-import apoc.util.Util;
-import org.assertj.core.api.Assertions;
 import org.junit.AfterClass;
 import org.junit.Before;
 import org.junit.BeforeClass;
@@ -25,10 +23,10 @@
 import static apoc.vectordb.VectorDbTestUtil.assertBerlinResult;
 import static apoc.vectordb.VectorDbTestUtil.assertLondonResult;
 import static apoc.vectordb.VectorDbTestUtil.assertNodesCreated;
+import static apoc.vectordb.VectorDbTestUtil.assertReadOnlyProcWithMappingResults;
 import static apoc.vectordb.VectorDbTestUtil.assertRelsCreated;
 import static apoc.vectordb.VectorDbTestUtil.dropAndDeleteAll;
 import static apoc.vectordb.VectorDbTestUtil.EntityType.*;
-import static apoc.vectordb.VectorDbUtil.ERROR_READONLY_MAPPING;
 import static apoc.vectordb.VectorEmbeddingConfig.ALL_RESULTS_KEY;
 import static apoc.vectordb.VectorEmbeddingConfig.MAPPING_KEY;
 import static apoc.vectordb.VectorMappingConfig.*;
@@ -231,7 +229,8 @@ MAPPING_KEY, map(EMBEDDING_KEY, "vect",
                     NODE_LABEL, "Test",
                     ENTITY_KEY, "myId",
                     METADATA_KEY, "foo",
-                    CREATE_KEY, true)
+                    MODE_KEY, MappingMode.CREATE_IF_MISSING.toString()
+                )
         );
 
         testResult(db, "CALL apoc.vectordb.chroma.queryAndUpdate($host, $collection, [0.2, 0.1, 0.9, 0.7], {}, 5, $conf)",
@@ -294,19 +293,22 @@ MAPPING_KEY, map(EMBEDDING_KEY, "vect",
         assertNodesCreated(db);
     }
 
+
     @Test
     public void getReadOnlyVectorsWithMapping() {
+        db.executeTransactionally("CREATE (:Test {readID: 'one'}), (:Test {readID: 'two'})");
+
         Map<String, Object> conf = map(ALL_RESULTS_KEY, true,
-                MAPPING_KEY, map(EMBEDDING_KEY, "vect"));
-
-        try {
-            testCall(db, "CALL apoc.vectordb.chroma.get($host, $collection, [1, 2], $conf)",
-                    map("host", HOST, "collection", COLL_ID.get(), "conf", conf),
-                    r -> fail()
-            );
-        } catch (RuntimeException e) {
-            Assertions.assertThat(e.getMessage()).contains(ERROR_READONLY_MAPPING);
-        }
+                MAPPING_KEY, map(NODE_LABEL, "Test",
+                        ENTITY_KEY, "readID",
+                        METADATA_KEY, "foo")
+        );
+
+        testResult(db, "CALL apoc.vectordb.chroma.get($host, $collection, ['1', '2'], $conf) " +
+                       "YIELD vector, id, metadata, node RETURN * ORDER BY id",
+                map("host", HOST, "collection", COLL_ID.get(), "conf", conf),
+                r -> assertReadOnlyProcWithMappingResults(r, "node")
+        );
     }
 
     @Test
@@ -338,17 +340,19 @@ MAPPING_KEY, map(EMBEDDING_KEY, "vect",
 
     @Test
     public void queryReadOnlyVectorsWithMapping() {
+        db.executeTransactionally("CREATE (:Start)-[:TEST {readID: 'one'}]->(:End), (:Start)-[:TEST {readID: 'two'}]->(:End)");
+
         Map<String, Object> conf = map(ALL_RESULTS_KEY, true,
-                MAPPING_KEY, map(EMBEDDING_KEY, "vect"));
-
-        try {
-            testCall(db, "CALL apoc.vectordb.chroma.query($host, $collection, [0.2, 0.1, 0.9, 0.7], {}, 5, $conf)",
-                    map("host", HOST, "collection", COLL_ID.get(), "conf", conf),
-                    r -> fail()
-            );
-        } catch (RuntimeException e) {
-            Assertions.assertThat(e.getMessage()).contains(ERROR_READONLY_MAPPING);
-        }
+                MAPPING_KEY, map(
+                        REL_TYPE, "TEST",
+                        ENTITY_KEY, "readID",
+                        METADATA_KEY, "foo")
+        );
+
+        testResult(db, "CALL apoc.vectordb.chroma.query($host, $collection, [0.2, 0.1, 0.9, 0.7], {}, 5, $conf)",
+                map("host", HOST, "collection", COLL_ID.get(), "conf", conf),
+                r -> assertReadOnlyProcWithMappingResults(r, "rel")
+        );
     }
 
     @Test