Merge branch '5.x' into 6.x

Author: mjfwebb

.gitignore

@@ -23,6 +23,7 @@
 .scala_dependencies
 .settings
 .shell_history
+.vscode/
 Thumbs.db
 \#*
 bin/teamcity/

modules/ROOT/content-nav.adoc

@@ -10,6 +10,7 @@
 ** xref:security/configuration.adoc[]
 ** xref:security/authentication.adoc[]
 ** xref:security/authorization.adoc[]
+** xref:security/subscriptions-authorization.adoc[]
 ** xref:security/impersonation-and-user-switching.adoc[]
 ** xref:security/operations.adoc[]
 * xref:types/index.adoc[]

modules/ROOT/pages/directives/autogeneration.adoc

@@ -15,7 +15,7 @@ This enables autogeneration of IDs for the field.
 The format of each generated ID is a UUID generated by the link:https://neo4j.com/docs/cypher-manual/current/functions/scalar/#functions-randomuuid[`randomUUID()` function].
 The field will not be present in input types for mutations.
 
-It is recommended to use xref::/directives/indexes-and-constraints.adoc#type-definitions-constraints-unique[`@unique`] in conjunction with this to add a unique node property constraint.
+It is recommended to use xref::/directives/indexes-and-constraints.adoc#_unique_node_property_constraints[`@unique`] in conjunction with this to add a unique node property constraint.
 
 === Definition
 

modules/ROOT/pages/directives/custom-logic.adoc

@@ -20,21 +20,17 @@ Global variables are available for use within the Cypher statement, and can be a
 a| 
 [source, graphql, indent=0]
 ----
-{
-  Movie {
-    title
-    actors: ACTED_IN @this {
-      role
-      actor {
-        name
-      }
-    }
-    directors: DIRECTED @this {
-      director {
-        name
-      }
-    }
-  }
+type Movie {
+    title: String
+    similarMovies(limit: Int = 10): [Movie]
+        @cypher(
+            statement: """
+            MATCH (this)<-[:ACTED_IN]-(:Actor)-[:ACTED_IN]->(rec:Movie)
+            WITH rec, COUNT(*) AS score ORDER BY score DESC
+            RETURN rec LIMIT $limit
+            """,
+            columnName: "rec"
+        )
 }
 ----
 
@@ -300,7 +296,6 @@ type Movie {
 }
 ----
 
-[[type-definitions-default-values-limit]]
 == `@limit`
 
 Available on nodes, this directive injects values into a query such as the `limit`.

modules/ROOT/pages/directives/database-mapping.adoc

@@ -183,7 +183,21 @@ The following query yields a different Cypher query depending on the user JWT:
   users {
     name
   }
-}ref::/directives/database-mapping.adoc#_declarerelationship[
+}
+----
+
+Assuming there is a user with the value `"username": "arthur"` in JWT, the Cypher query looks like:
+
+[source, cypher, indent=0]
+----
+MATCH (this:arthur)
+RETURN this { .name } as this
+----
+
+Similarly, context values can be passed directly:
+
+[source, graphql, indent=0]
+----
 type User @node(label: ["$context.appId"]) {
     name: String!
 }

modules/ROOT/pages/directives/index.adoc

@@ -14,7 +14,7 @@ The Neo4j GraphQL Library provides the following directives to be used whilst de
 | xref::/directives/database-mapping.adoc#_relationship[`@relationship`]
 | Configures xref::/types/relationships.adoc[relationships] between object types.
 
-| xref::/directives/database-mapping.adoc#_relationship_properties[`@relationshipProperties`]
+| xref::/directives/database-mapping.adoc#_relationshipproperties[`@relationshipProperties`]
 a| Required to differentiate interfaces that are used for relationship properties, and otherwise.
 
 | xref::/directives/database-mapping.adoc#type-definitions-node[`@node`]
@@ -40,14 +40,14 @@ a| Required to differentiate interfaces that are used for relationship propertie
 | xref::/security/authorization.adoc[`@authorization`]
 | Specifies authorization rules for queries and mutations on the type.
 
-| xref::/security/configuration.adoc#authentication-and-authorization-jwt[`@jwt`]
+| xref::/security/configuration.adoc#_the_jwt_directive[`@jwt`]
 | Configures the JWT authentication and authorization filters to include additional JWT claims.
 
-| xref::/security/configuration.adoc#_nested_claims[`@jwtClaim`]
+| xref::/security/configuration.adoc#_the_jwtclaim_directive[`@jwtClaim`]
 | Used in combination with `@jwt`.
 Configures the JWT authentication and authorization filters to include an additional JWT claim which is either nested or using special characters not supported by GraphQL.
 
-| `@subscriptionsAuthorization`
+| xref::/security/subscriptions-authorization.adoc[`@subscriptionsAuthorization`]
 | Specifies authorization rules for subscriptions on the type.
 
 |===
@@ -105,12 +105,15 @@ Particularly useful for types that are not correctly pluralized or are non-Engli
 |===
 | Directive | Description
 
-| xref::/directives/indexes-and-constraints.adoc#type-definitions-indexes-fulltext[`@fulltext`]
+| xref::/directives/indexes-and-constraints.adoc#_fulltext_indexes[`@fulltext`]
 | Indicates that there should be a fulltext index inserted into the database for the specified Node and its properties.
 
-| xref::/directives/indexes-and-constraints.adoc#type-definitions-constraints-unique[`@unique`]
+| xref::/directives/indexes-and-constraints.adoc#_unique_node_property_constraints[`@unique`]
 | Indicates that there should be a uniqueness constraint in the database for the fields that it is applied to.
 
+| xref::/directives/indexes-and-constraints.adoc#_vector_index_search[`@vector`]
+| Perform a vector index search on your database either based by passing in a vector index or a search phrase. label:beta[]
+
 |===
 
 == Custom logic

modules/ROOT/pages/directives/indexes-and-constraints.adoc

@@ -247,3 +247,191 @@ const schema = await neoSchema.getSchema();
 
 await neoSchema.assertIndexesAndConstraints({ options: { create: true }});
 ----
+
+
+:description: Directives related to generative AI in the Neo4j GraphQL Library.
+
+[role=label--beta]
+== Vector index search
+
+With the `@vector` GraphQL directive you can query your database to perform a vector index search.
+Queries are performed by passing in either a vector index or a query phrase.
+
+A query by vector index finds nodes with a vector embedding similar to that index.
+That is, the query performs a nearest neighbor search.
+
+In contrast, a query by phrase (a string of text) forwards the phrase to the link:https://neo4j.com/docs/cypher-manual/current/genai-integrations/[Neo4j GenAI plugin] and the plugin generates a vector embedding for it.
+This embedding is then compared to the node vector embeddings in the database.
+
+[NOTE] 
+.Prerequisites
+==== 
+* The database must be Neo4j version 5.15 or higher.
+* The node vector embeddings already exist in the database. See link:https://neo4j.com/docs/cypher-manual/current/indexes/semantic-indexes/vector-indexes/[Vector indexes] to learn more about vector indexes in Cypher and Neo4j.
+* The embeddings must have been created using the same method, that is, the same provider and model. See link:https://neo4j.com/docs/genai/tutorials/embeddings-vector-indexes/[Embeddings & Vector Indexes Tutorial] to learn about vector embeddings in Cypher and Neo4j.
+* Queries by vector index cannot be performed across multiple labels.
+* Queries by phrase require credentials for the Neo4j GenAI plugin.
+====
+
+[NOTE]
+====
+Vector index searches are _read-only_ in the sense that the data which the queries operate on are retrieved from the database but not altered or written back to the database.
+====
+
+
+=== Definition
+
+[source, graphql]
+----
+"""Informs @neo4j/graphql that there should be a vector index in the database, allows users to search by the index in the generated schema."""
+directive @vector(indexes: [VectorIndexInput]!) on OBJECT
+----
+
+`VectorIndexInput` is defined as follows:
+
+[source, graphql]
+----
+input VectorIndexInput {
+  """(Required) The name of the vector index."""
+  indexName: String!
+  """(Required) The name of the embedding property on the node."""
+  embeddingProperty: String!
+  """(Required) The name of the query."""
+  queryName: String
+  """(Optional) The name of the provider."""
+  provider: String
+}
+----
+
+If the optional field `provider` is set, the type is used for a query by phrase, otherwise for a query by vector.
+Allowed values for the `provider` field are defined by the available link:https://neo4j.com/docs/cypher-manual/current/genai-integrations/#ai-providers[GenAI providers].
+
+
+=== Usage
+
+==== Query by vector index
+
+Perform a nearest neighbor search by passing a vector to find nodes with a vector embedding similar to that vector.
+
+.Type definition
+[source, graphql]
+----
+type Product @vector(indexes: [{
+  indexName: "productDescriptionIndex",
+  embeddingProperty: "descriptionVector",
+  queryName: "searchByDescription"
+}]) {
+  id: ID!
+  name: String!
+  description: String!
+}
+----
+
+This defines the query to be performed on all `Product` nodes which have a vector index named `productDescriptionIndex` for the property `descriptionVector`, implying that a vector embedding has been created for the `description` property of each node. 
+
+.Example query
+[source, graphql]
+----
+query FindSimilarProducts($vector: [Float]!) {
+  searchByDescription(vector: $vector) {
+    productsConnection {
+      edges {
+        cursor
+        score
+        node {
+            id
+            name
+            description
+        }
+      }
+    }
+  }
+}
+----
+
+The input `$vector` is a list of `FLOAT` values and should look similar to this:
+
+.An example vector
+[source, graphql]
+----
+{
+  "vector": [
+    0.123456,
+    ...,
+    0.654321,
+  ]
+}
+----
+
+The query returns all `Product` nodes with a vector embedding on their `descriptionVector` property which is similar to the query argument `$vector`.
+
+==== Query by phrase
+
+Perform a query which utilizes the link:https://neo4j.com/docs/cypher-manual/current/genai-integrations/[Neo4j GenAI plugin] to create a vector embedding for a search phrase and then compare it to existing vector embeddings on nodes in the database.
+
+[NOTE]
+====
+Requires credentials for the plugin.
+====
+
+Ensure your provider credentials are set in the call to Neo4jGraphQL, for example:
+
+.Feature configuration
+[source, graphql]
+----
+const neoSchema = new Neo4jGraphQL({
+    typeDefs,
+    driver,
+    features: {
+        vector: {
+            OpenAI: {
+                token: "my-open-ai-token",
+                model: "text-embedding-3-small",
+            },
+        },
+    },
+});
+----
+
+`OpenAI` is one of the GenAI providers for generating vector embeddings.
+See link:https://neo4j.com/docs/cypher-manual/current/genai-integrations/#ai-providers[GenAI providers] for the full list of providers and their respective identifiers.
+
+.Type definition
+[source, graphql]
+----
+type Product @vector(indexes: [{
+  indexName: "productDescriptionIndex",
+  embeddingProperty: "descriptionVector",
+  provider: OPEN_AI,  # Assuming this is configured in the server
+  queryName: "searchByPhrase"
+}]) {
+  id: ID!
+  name: String!
+  description: String!
+}
+----
+
+This defines the query to be performed on all `Product` nodes which have a vector index named `productDescriptionIndex` for the property `descriptionVector`, implying that a vector embedding has been created for the `description` property of each node. 
+
+.Example query
+[source, graphql]
+----
+query SearchProductsByPhrase($phrase: String!) {
+  searchByPhrase(phrase: $phrase) {
+    productsConnection {
+      edges {
+        cursor
+        score
+        node {
+            id
+            name
+            description
+        }
+      }
+    }
+  }
+}
+----
+
+First, the query passes the query phrase argument `$phrase` to the GenAI plugin and lets it generate a vector embedding for the phrase.
+Then it returns all `Product` nodes with a vector embedding on their `descriptionVector` property which are similar to the vector embedding generated by the plugin.

modules/ROOT/pages/directives/schema-configuration/type-configuration.adoc

@@ -115,11 +115,11 @@ This directive is used to limit subscription operations in the library.
 [source, graphql, indent=0]
 ----
 enum SubscriptionFields {
-    CREATE
-    UPDATE
-    DELETE
-    CREATE_RELATIONSHIP
-    DELETE_RELATIONSHIP
+    CREATED
+    UPDATED
+    DELETED
+    RELATIONSHIP_CREATED
+    RELATIONSHIP_DELETED
 }
 
 directive @subscription(events: [SubscriptionFields!]! = [CREATED, UPDATED, DELETED, RELATIONSHIP_CREATED, RELATIONSHIP_DELETED]) on OBJECT | SCHEMA
@@ -210,4 +210,4 @@ This way, instead of the wrongly generated `teches`, the type is properly writte
 ----
 
 The same is applied to other operations such as `createTechs`. 
-However, keep in mind that database labels are not changed with this directive.
+However, keep in mind that database labels are not changed with this directive.

modules/ROOT/pages/driver-configuration.adoc

@@ -216,9 +216,7 @@ await ogm.checkNeo4jCompat();
 
 == Specifying the Neo4j database
 
-There are two ways to specify which database within a DBMS should be used.
-
-=== Context
+Specify the database to be used within your DBMS via the `database` field under `sessionConfig` in the `context` that all resolvers share.
 
 [source, javascript, indent=0]
 ----

modules/ROOT/pages/getting-started/index.adoc

@@ -5,8 +5,6 @@
 
 This tutorial walks you through creating a new project with the Neo4j GraphQL Library.
 
-If you are not familiar with Neo4j and GraphQL, you can alternatively take the course https://graphacademy.neo4j.com/courses/graphql-basics/?ref=docs[Introduction to Neo4j & GraphQL] in GraphAcademy to learn the fundamentals, how to use the xref:getting-started/toolbox.adoc[Neo4j GraphQL Toolbox] and the Neo4j GraphQL Library to create GraphQL APIs backed by a Neo4j graph database.
-
 This tutorial shows you how to:
 
 - Install the Neo4j GraphQL Library and its dependencies.
@@ -294,3 +292,6 @@ By now, you should have a GraphQL API connected to a Neo4j database, to which yo
 
 To learn more, keep reading the documentation about xref:queries-aggregations/index.adoc[Queries and aggregations] or alternatively learn how to use the xref:getting-started/toolbox.adoc[Neo4j GraphQL Toolbox].
 For more advanced database settings, refer to the xref:driver-configuration.adoc[Driver configuration] page.
+
+// Edit at: https://github.com/neo4j-graphacademy/courses/blob/main/asciidoc/courses/graphql-basics/promo.adoc
+include::https://raw.githubusercontent.com/neo4j-graphacademy/courses/main/asciidoc/courses/graphql-basics/promo.adoc[]