Raphael/v24 graphql (#669)

Add content of alpha and alpha3 posts in doc for v24.

---------

Co-authored-by: Gajanan <[email protected]>

Author: rderbier

content/graphql/mutations/mutations-overview.md

@@ -221,6 +221,35 @@ mutation {
 }
 ```
 
+## Vector Embedding mutations
+
+For types with vector embeddings Dgraph automatically generates the add mutation. For this example of add mutation we use the following schema.
+
+```graphql
+type User {
+    userID: ID!
+    name: String!
+    name_v: [Float!] @embedding @search(by: ["hnsw(metric: euclidean, exponent: 4)"])
+}
+
+mutation {
+addUser(input: [
+{ name: "iCreate with a Mini iPad", name_v: [0.12, 0.53, 0.9, 0.11, 0.32] },
+{ name: "Resistive Touchscreen", name_v: [0.72, 0.89, 0.54, 0.15, 0.26] },
+{ name: "Fitness Band", name_v: [0.56, 0.91, 0.93, 0.71, 0.24] },
+{ name: "Smart Ring", name_v: [0.38, 0.62, 0.99, 0.44, 0.25] }]) 
+  {
+    project {
+      id
+      name
+      name_v
+    }
+  }
+}
+```
+
+Note: The embeddings are generated outside of Dgraph using any suitable machine learning model.
+
 ## Examples
 
 You can refer to the following [link](https://github.com/dgraph-io/dgraph/tree/main/graphql/schema/testdata/schemagen) for more examples.

content/graphql/queries/aggregate.md

@@ -1,7 +1,7 @@
 +++
 title = "Aggregate Queries"
 description = "Dgraph automatically generates aggregate queries for GraphQL schemas. These are compatible with the @auth directive."
-weight = 3
+weight = 4
 [menu.main]
     parent = "graphql-queries"
     name = "Aggregate Queries"

content/graphql/queries/vector-similarity.md

@@ -0,0 +1,64 @@
++++
+title = "Similarity Search"
+description = "Dgraph automatically generates GraphQL queries for each vector index that you define in your schema. There are two types of queries generated for each index."
+weight = 3
+[menu.main]
+    parent = "graphql-queries"
+    identifier = "vector-queries"
++++
+
+Dgraph automatically generates two GraphQL similarity queries for each type that have at least one [vector predicate](/graphql/schema/types/#vectors) with `@search` directive.
+
+For example
+
+```graphql
+type User {
+    id: ID!
+    name: String!
+    name_v: [Float!] @embedding @search(by: ["hnsw(metric: euclidean, exponent: 4)"])
+}
+```
+
+With the above schema, the auto-generated `querySimilar<Object>ByEmbedding` query allows us to run similarity search using the vector index specified in our schema.
+
+```graphql
+getSimilar<Object>ByEmbedding(
+    by: vector_predicate, 
+    topK: n, 
+    vector: searchVector): [User]
+```
+
+For example in order to find top 3 users with names similar to a given user name embedding the following query function can be used. 
+
+```graphql  
+querySimilarUserByEmbedding(by: name_v, topK: 3, vector: [0.1, 0.2, 0.3, 0.4, 0.5]) {
+        id
+        name
+        vector_distance
+     }
+```
+The results obtained for this query includes the 3 closest Users ordered by vector_distance. The vector_distance is the Euclidean distance between the name_v embedding vector and the input vector used in our query.
+
+Note: you can omit vector_distance predicate in the query, the result will still be ordered by vector_distance.
+
+The distance metric used is specified in the index creation. 
+
+Similarly, the auto-generated `querySimilar<Object>ById` query allows us to search for similar objects to an existing object, given it’s Id. using the  function.
+
+```graphql
+getSimilar<Object>ById(
+    by: vector_predicate, 
+    topK: n, 
+    id: userID):  [User]
+```
+
+For example the following query searches for top 3 users whose names are most similar to the name of the user with id "0xef7".
+
+```graphql
+querySimilarUserById(by: name_v, topK: 3, id: "0xef7") {
+    id
+    name
+    vector_distance
+}
+```
+

content/graphql/schema/directives/_index.md

@@ -38,6 +38,12 @@ Reference: [Deprecation]({{< relref "deprecated.md" >}})
 
 Reference: [@dgraph directive]({{< relref "directive-dgraph" >}})
 
+### @embedding
+
+`@embedding` directive designates one or more fields as vector embeddings.
+
+Reference: [@embedding directive]({{< relref "embedding" >}})
+
 ### @generate
 
 The `@generate` directive is used to specify which GraphQL APIs are generated for a type.

content/graphql/schema/directives/embedding.md

@@ -0,0 +1,13 @@
++++
+title = "@embedding"
+weight = 1
+[menu.main]
+    parent = "directives"
++++
+
+
+A Float array can be used as a vector using `@embedding` directive. It denotes a vector of floating point numbers, i.e an ordered array of float32. 
+
+The embeddings can be defined on one or more predicates of a type and they are generated using suitable machine learning models.
+
+This directive is used in conjunction with `@search` directive to declare the HNSW index. For more information see: [@search](/graphql/schema/directives/search/#vector-embedding) directive for vector embeddings.

content/graphql/schema/directives/search.md

@@ -624,3 +624,23 @@ query {
   }
 }
 ```
+
+### Vector embedding
+
+The `@search` directive is used in conjunction with `@embeding` directive to define the HNSW index on vector embeddings. These vector embeddings are obtained from external Machine Learning models.
+
+```graphql
+type User {
+    userID: ID!
+    name: String!
+    name_v: [Float!] @embedding @search(by: ["hnsw(metric: euclidean, exponent: 4)"])
+}
+```
+
+In this schema, the field `name_v` is an embedding on which the HNSW algorithm is used to create a vector search index. 
+
+The metric used to compute the distance between vectors (in this example) is Euclidean distance. Other possible metrics are `cosine` and `dotproduct`.
+
+The directive, `@embedding`, designates one or more fields as vector embeddings.
+
+The `exponent` value is used to set reasonable defaults for HNSW internal tuning parameters. It is an integer representing an approximate number for the vectors expected in the index, in terms of power of 10. Default is “4” (10^4 vectors).

content/graphql/schema/types.md

@@ -51,6 +51,26 @@ type User {
 
 Scalar lists in Dgraph act more like sets, so `tags: [String]` would always contain unique tags.  Similarly, `recentScores: [Float]` could never contain duplicate scores.
 
+### Vectors
+
+A Float array can be used as a vector using `@embedding` directive. It denotes a vector of floating point numbers, i.e an ordered array of float32. A type can contain more than one vector predicate.
+
+Vectors are normaly used to store embeddings obtained from an ML model. 
+
+When a Float vector is indexed, the GraphQL `querySimilar<type name>ByEmbedding` and `querySimilar<type name>ById` functions can be used for [similarity search]({{<relref "vector-similarity.md">}}).
+
+A simple example of adding a vector embedding on `name`  to `User` type is shown below. 
+
+```graphql
+type User {
+    userID: ID!
+    name: String!
+    name_v: [Float!] @embedding @search(by: ["hnsw(metric: euclidean, exponent: 4)"])
+}
+```
+
+In this schema, the field `name_v` is an embedding on which the [@search ](/graphql/schema/directives/search/#vector-embedding) directive for vector embeddings is used.
+
 ### The `ID` type
 
 In Dgraph, every node has a unique 64-bit identifier that you can expose in GraphQL using the `ID` type. An `ID` is auto-generated, immutable and never reused. Each type can have at most one `ID` field.