diff --git a/docs/connectors/mongodb/_category_.json b/docs/connectors/mongodb/_category_.json new file mode 100644 index 000000000..6161c32c6 --- /dev/null +++ b/docs/connectors/mongodb/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "MongoDB", + "position": 7 +} diff --git a/docs/connectors/mongodb/config.mdx b/docs/connectors/mongodb/config.mdx new file mode 100644 index 000000000..692b1f595 --- /dev/null +++ b/docs/connectors/mongodb/config.mdx @@ -0,0 +1,289 @@ +--- +sidebar_position: 2 +sidebar_label: Configuration +description: + "Reference documentation for the setup process for the Hasura MongoDB connector, including connection URI details, + native queries, and native mutations." +keywords: + - hasura mongodb setup + - connector configuration + - graphql api integration + - database connection uri + - native queries + - native mutations + - graphql mutations + - data modeling + - api customization + - hasura configuration guide + - database schema management +seoFrontMatterUpdated: true +--- + +# Configuration + +:::warning Subject to change + +During this active development phase, the configuration structure is subject to change. + +::: + +## Introduction + +This document is the reference documentation for the MongoDB data connector configuration. Configuration is +currently broken down into 3 folders and a root configuration file. +1. [`configuration.json`](#root-configuration-file) +2. [`schema`](#schema) +3. [`native_queries`](#native-queries) +4. [`native_mutations`](#native-mutations) + +### Root Configuration File + +The root configuration file serves as a central point for configuring various aspects of the system. Below is an example +configuration file along with explanations of its components: + +**Example** + +```json +{ + "introspectionOptions": { + "sampleSize": 100, + "noValidatorSchema": false, + "allSchemaNullable": true + } +} +``` + +#### `introspectionOptions` + +The `introspectionOptions` section allows customization of options related to introspection, which is +the process of examining or analyzing the system's structure and capabilities. + +- `sampleSize`: Specifies the size of the sample used for introspection. In the provided example, the sample size is set +to 100. Adjust this value as needed based on the requirements and characteristics of your system. + - **Default**: `100` +- `noValidatorSchema`: Determines whether to include a validator schema during introspection. When set to false, a +validator schema will be included. In the example, it's set to false, indicating that a validator schema will be +included if one exists. + - **Default**: `false` +- `allSchemaNullable`: Indicates whether all schema elements are nullable. When set to true, all schema elements are +considered nullable. This setting can impact how the system handles data validation and type checking. In the example, +it's set to true, implying that all schema elements are nullable. + - **Default**: `true` + +The `.configuration_metadata` file is a blank file with no content. It's used by the system as a marker to check if the +`configuration.json` file has been modified. Essentially, its presence alone serves as an indicator that the +configuration file has been updated since the last check. This simple mechanism helps the system keep track of changes +to the configuration without storing any actual timestamps or data. + +### Schema + +The `schema` directory contains JSON files of all collections that were introspected in your database. + +**Example** + +```json +{ + "name": "users", + "collections": { + "users": { + "type": "users" + } + }, + "objectTypes": { + "users": { + "fields": { + "_id": { + "type": { + "scalar": "objectId" + } + }, + "email": { + "type": { + "scalar": "string" + } + }, + "name": { + "type": { + "scalar": "string" + } + }, + "password": { + "type": { + "scalar": "string" + } + } + } + } + } +} +``` + +#### Name + +The `name` property specifies the name which gets exposed to Hasura metadata/tooling: + +```json +{ + "name": "users" +} +``` + +#### Collections + +The `collections` property contains definitions of the collection name in your database and the object type it returns: + +```json +{ + "collections": { + "users": { + "type": "users" + } + } +} +``` + +#### Object types + +The `objectTypes` property defines the returned object types. Object types contain `fields` that specify either +scalar or other structural object types. + +```json +{ + "objectTypes": { + "users": { + "fields": { + "_id": { + "type": { + "scalar": "objectId" + } + }, + "email": { + "type": { + "scalar": "string" + } + }, + "name": { + "type": { + "scalar": "string" + } + }, + "password": { + "type": { + "scalar": "string" + } + } + } + } + } +} +``` + +### Type Examples + +```json +{ "type": { "scalar": "string" } } +``` + +```json +{ "type": "extended_json" } +``` + +```json +{ "type": { "arrayOf": { "scalar": "string" } } } +``` + +```json +{ "type": { "object": "TypeName" } } +``` + +```json +{ "type": { "nullable": { "scalar": "string" } } } +``` + + +#### Scalar Types + +- `double`: Represents a floating point number. +- `string`: Represents a sequence of characters. +- `bool`: Represents a boolean value, true or false. +- `int`: Represents an integer. +- `long`: Represents a longer form of integer. +- `decimal`: Represents a large decimal number. +- `date`: Represents a date, stored as a string in ISO format. +- `timestamp`: Represents a Unix timestamp. +- `objectId`: Represents an object identifier. + +#### Structural Types + +- `object`: Represents a BSON document or an embedded document. Users can define their own nested object types, +specifying the structure of these objects as required by their applications. +- `arrayOf`: Represents an array of elements, with each element being a type specified after `arrayOf`. For instance, +`{"arrayOf" : "string"}` means an array of strings. + +### Native queries + +Native queries are named MongoDB [aggregation pipelines][MongoDB: pipeline] that you specify in the data connector +configuration. They are similar to a database view, but more expressive as they admit parameters similar to a function +and do not require any DDL permissions on the database. See the configuration reference on [Native +Queries](#updating-with-introspection). + +More information in the [Native Queries](/connectors/mongodb/native-queries) documention. + +### Native mutations {#native-mutations} + +Native mutations are named MongoDB [runCommand][MongoDB: runCommand] operations that you specify in the data connector +configuration. These are commonly used for mutations, but we do support the full [runCommand][MongoDB: runCommand] API. +See the configuration reference on [Native Mutations](#updating-with-introspection). + +More information in the [Native Mutations](/connectors/mongodb/native-mutations/index.mdx) documentation. + +## Configuration workflows + +The data connector provides a plugin to the hasura CLI to assist you in authoring configuration. + +We provide the `mongodb-cli-plugin`, which is a small executable, of which the builds can be accessed +[here](https://github.com/hasura/ndc-mongodb/releases/). + +:::warning Current status + +The intended way to use this plugin is through the main `ddn` CLI. + +But at the time of this writing, this part of the developer experience is undergoing active development, so the exact +command invocations are likely to change. + +::: + +### Updating with introspection {#updating-with-introspection} + +Whenever the schema of your database changes you will need to update your data connector configuration accordingly to +reflect those changes. + +Running `mongodb-cli-plugin update` in a directory will do the following: + +Connect to the database with the specified `connection-uri`, create a `schema` directory, if one does not exist, and +then either create or update a file for each collection that is introspected in your database. + +Currently, the `mongodb-cli-plugin` tries to use any validation schemas if they exist, and falls back to sampling +documents in your collection. The current sample size is 10. This will be configurable in future releases. + +### Manually editing + +There are occasions when the automatic introspection falls short of your needs. For instance, it may not detect a +particular entity type, or it may pick names according to conventions you disagree with. + +:::note + +This only applies to the files under the `schema` directory + +::: + +If you find yourself in this situation you are still able to bring your configuration into an acceptable state by +editing it manually. In this case you'd be well advised to keep your configuration files under version control, as +re-running the `update` command will overwrite your manually-crafted changes. + +[Native Queries](/connectors/mongodb/native-queries) and +[Native Mutations](/connectors/mongodb/native-mutations/index.mdx) will always need manual authorship currently. We +plan on improving this authorship flow in the future. + +[MongoDB: pipeline]: https://www.mongodb.com/docs/manual/core/aggregation-pipeline +[MongoDB: runCommand]: https://www.mongodb.com/docs/manual/reference/method/db.runCommand diff --git a/docs/connectors/mongodb/index.mdx b/docs/connectors/mongodb/index.mdx new file mode 100644 index 000000000..c7c543ab4 --- /dev/null +++ b/docs/connectors/mongodb/index.mdx @@ -0,0 +1,135 @@ +--- +sidebar_position: 1 +sidebar_label: MongoDB +description: "Dive into the Hasura's Native Data Connector for MongoDB." +keywords: + - hasura + - mongodb + - data connector + - graphql + - queries + - nosql data types + - graphql types + - configuration + - api + - database +seoFrontMatterUpdated: true +--- + +# Native Data Connector for MongoDB + +## Introduction + +The MongoDB Native Data Connector for Hasura DDN expands our connectivity options, enabling integration with +MongoDB noSQL databases. Here we'll provide an overview of the features offered by the MongoDB connector and guide +you through the configuration process within a Hasura DDN project. + +The MongoDB data connector makes any database resource listed in its configuration available. In order to populate +the configuration, the connector supports introspecting the database via the Hasura CLI `update` command. + +## Queryable collections + +The MongoDB data connector supports several types of queryable collections: + +- Tables +- Views +- Native queries +- Native mutations + +**Tables and views** are typically discovered automatically during the introspection process. + +**Native queries** are enabled via MongoDB's [aggregation pipelines][MongoDB: pipeline], and are defined in the +MongoDB data connector's configuration. They are similar to a view but more expressive as they allow parameters +similar to functions and do not require any DDL permissions on the database. See the configuration reference on +[Native Queries](/connectors/mongodb/native-queries). + +**Native mutations** in MongoDB are enabled via a [runCommand][MongoDB: runCommand] and are also defined in the +MongoDB data connector's configuration. These are commonly used for simple data mutations, but we do support the +full [runCommand][MongoDB: runCommand] API too. See the configuration reference on +[Native Mutations](/connectors/mongodb/native-mutations). + +## Data types + +The Hasura MongoDB data connector supports any data type that MongoDB knows how encode and decode as JSON - No data +type is handled as a special case. + +### Data type naming + +Many data types have aliases in MongoDB, which can be found in the +[MongoDB documentation on data types][MongoDB: data types]. + +In order to use standard GraphQL data types rather than custom data types in the resulting GraphQL schema, the +Hasura supergraph configuration enables expressing a mapping between data connector types and GraphQL types. + +### BSON support + +MongoDB stores data in BSON, while the GraphQL API uses JSON. Hasura converts query responses to JSON according to the +types defined in the Hasura schema configuration. For example, + +- `double` and `int` (64-bit floating-point numbers, and 32-bit integers) are converted to JSON numbers +- `long` and `decimal` (64-bit integers, and 128-bit floating point numbers) are converted to JSON strings to avoid loss + of precision +- dates are converted to strings in ISO 8601 format +- object IDs are converted to hex-encoded strings + +If there is a value in a query response that does not match the type defined in the Hasura schema configuration then the +query will fail with an error. + +In some cases it is not possible to configure a specific type for a collection field. For example if a field contains +different types of data in different documents since Hasura does not implement union types. In those cases the +configured type of a field may be `extendedJSON`. This is a fallback that captures any values that can be represented in +BSON. To preserve type information values of this type are converted to JSON according to the canonical variation of the +[MongoDB Extended JSON v2 spec](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json/). For example, + +- numbers are converted to objects with a type tag and a string value, like `{ "$numberDouble": "3.14" }` +- dates are converted to the form, `{"$date": {"$numberLong": "" } }` +- object IDs are converted to this form, `{ "$oid": "" }` + +Queries may include input values in the form of arguments. These are converted from JSON to BSON according to the +inverse of the above. For example, + +- if the type of an argument is `double` then a valid input is `3.14`. +- if the type of an argument is `extendedJSON` then either `{ "$numberDouble": "3.14" }` or `3.14` is valid. + +In general if an argument value does not match the expected type then the query will fail with an error. But there are a +few cases where we apply implicit conversion where the BSON types have indistinguishable JSON representations. In +particular, it is permissible to provide a GraphQL `Int` value where a `double` is expected, or to provide a GraphQL +`Float` value where an `int` is expected. + +## Queries + +The Hasura MongoDB data connector supports all query operations; see the +[query documentation](/graphql-api/queries/index.mdx) for details. + +### Filtering + +The MongoDB data connector supports the introspection and usage of all binary comparison functions and operators +defined for any tracked scalar type, built-in and user-defined alike. Refer to +[filters documentation](/graphql-api/queries/filters/index) for more information. + +## Mutations + +Mutations are still undergoing active development and are likely to change in the future. Currently, you can write your +own mutations using [Native Mutations](/connectors/mongodb/native-mutations). + +## Troubleshooting the MongoDB Connector + +### I'd like to tweak how the connector works or does database introspection + +Visit the [Configuration page](/connectors/mongodb/config.mdx) for more information. + +### unprocessable content: error converting MongoDB response to JSON: expected a value of type Scalar(String), but got null + +This happens when there is a discrepancy between types in the database data and the schema that was generated. + +Usually this can happen when sampling determined that a field was non-nullable when in fact it is a nullable field. +In this case you manually update the proper collections schema json file in the `schema` directory to be non-nullable. + +### I'm having issues getting my Native Query to run + +More information can be found in the [Native Queries Requirements](/connectors/mongodb/native-queries/index.mdx) +section. + +[MongoDB: pipeline]: https://www.mongodb.com/docs/manual/core/aggregation-pipeline +[MongoDB: runCommand]: https://www.mongodb.com/docs/manual/reference/method/db.runCommand +[MongoDB: data types]: https://www.mongodb.com/docs/manual/reference/bson-types diff --git a/docs/connectors/mongodb/native-mutations/_category_.json b/docs/connectors/mongodb/native-mutations/_category_.json new file mode 100644 index 000000000..a1822fff3 --- /dev/null +++ b/docs/connectors/mongodb/native-mutations/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Native Mutations", + "position": 3 +} diff --git a/docs/connectors/mongodb/native-mutations/index.mdx b/docs/connectors/mongodb/native-mutations/index.mdx new file mode 100644 index 000000000..fe08bdbd5 --- /dev/null +++ b/docs/connectors/mongodb/native-mutations/index.mdx @@ -0,0 +1,25 @@ +--- +sidebar_position: 2 +sidebar_label: Native Mutations +description: + "Native mutations allow you to run custom database commands on your MongoDB database that uses runCommand API. + This allows you to run queries/mutations that are not supported by Hasura's GraphQL engine. This page explains how + to configure various types of native queries in Hasura." +keywords: + - native mutations +seoFrontMatterUpdated: false +--- + +# Native Mutations + +## Introduction + +Native Mutations allow you to run custom mutations on your MongoDB database using the +[runCommand](https://www.mongodb.com/docs/manual/reference/method/db.runCommand) API. This allows you to run mutations +that are not supported by Hasura DDN's GraphQL engine. + +This unlocks the full power of your database and the +[runCommand](https://www.mongodb.com/docs/manual/reference/method/db.runCommand) API, allowing you to run complex +pipelines, and mutations — all directly from your Hasura GraphQL API. + +You can check out [Native Mutations](/connectors/mongodb/native-mutations/intro-and-setup.mdx) here. diff --git a/docs/connectors/mongodb/native-mutations/intro-and-setup.mdx b/docs/connectors/mongodb/native-mutations/intro-and-setup.mdx new file mode 100644 index 000000000..f3d241f4c --- /dev/null +++ b/docs/connectors/mongodb/native-mutations/intro-and-setup.mdx @@ -0,0 +1,102 @@ +--- +sidebar_position: 1 +sidebar_label: Custom Mutations +description: + "Custom mutations allow you to run custom commands on your MongoDB database using the runCommand API. This page explains + how to configure custom mutations in Hasura." +keywords: + - native mutations + - custom mutations +seoFrontMatterUpdated: false +--- + +# Native Mutations + +## Introduction + +Native mutations allow you to run custom commands on your MongoDB database using the [runCommand][MongoDB: runCommand] +API that can be exposed via the Hasura GraphQL and modify the database state. As point-to-point mutations are not yet +supported, this is one way to mutate data using your GraphQL API. + +## Setup + +Native mutations can be defined by +1. Adding a `native_mutations` directory if one doesn't already exist in your connector configuration directory +2. Adding a `.json` file following the syntax laid out in the following sections. + +## Example + +Here's an example of simple `"insert_artist"` native mutation: + +### Configuration + +```json +{ + "name": "insertArtist", + "description": "Example of a database insert using a native mutation", + "resultType": { + "object": "InsertArtist" + }, + "arguments": { + "artistId": { + "type": { + "scalar": "int" + } + }, + "name": { + "type": { + "scalar": "string" + } + } + }, + "objectTypes": { + "InsertArtist": { + "fields": { + "ok": { + "type": { + "scalar": "int" + } + }, + "n": { + "type": { + "scalar": "int" + } + } + } + } + }, + "command": { + "insert": "Artist", + "documents": [ + { + "ArtistId": "{{ artistId }}", + "Name": "{{ name }}" + } + ] + } +} +``` + +This will create a mutation called `"insertUser"` which takes two arguments called `"artistId"` of type `int`, and +`"name"` of type `string`. The query will return an object with the keys `"ok"` and `"n"` and the values as `int`s. + +:::tip Valid Native Mutation Syntax + +Check out our page on writing valid Hasura DDN [Native Query syntax](/connectors/mongodb/native-mutations/syntax.mdx). + +::: + +### Usage + +With the example above, you can then use the query in your GraphQL API like this: + +```graphql +mutation MyMutation { + app_insertArtist(artistId: 10000, name: "Pearl Jam") { + ok + n + } +} +``` + +[MongoDB: runCommand]: https://www.mongodb.com/docs/manual/reference/method/db.runCommand diff --git a/docs/connectors/mongodb/native-mutations/syntax.mdx b/docs/connectors/mongodb/native-mutations/syntax.mdx new file mode 100644 index 000000000..716933987 --- /dev/null +++ b/docs/connectors/mongodb/native-mutations/syntax.mdx @@ -0,0 +1,370 @@ +--- +sidebar_position: 2 +sidebar_label: Syntax +description: Learn how to write native mutations for MongoDB with the proper syntax in Hasura. +keywords: + - hasura + - native mutations + - troubleshooting + - runCommand + - gotchas +seoFrontMatterUpdated: false +--- + +# Native Mutation MongoDB Syntax + +Command to run via MongoDB's `runCommand` API. For details on how to write commands see +https://www.mongodb.com/docs/manual/reference/method/db.runCommand/ + +The command is read as Extended JSON. It may be in canonical or relaxed format, or +a mixture of both. +See https://www.mongodb.com/docs/manual/reference/mongodb-extended-json/ + +Keys and values in the command may contain placeholders of the form `{{variableName}}` +which will be substituted when the native procedure is executed according to the given +arguments. + +Placeholders must be inside quotes so that the command can be stored in JSON format. If the +command includes a string whose only content is a placeholder, when the variable is +substituted the string will be replaced by the type of the variable. For example in this +command, + +```json +{ + "insert": "posts", + "documents": "{{ documents }}" +} +``` + +If the type of the `documents` argument is an array then after variable substitution the +command will expand to: + +```json +{ + "insert": "posts", + "documents": [/* array of documents */] +} +``` + +## Examples + +### Insert +```json + "name": "insertArtist", + "description": "Example of a database insert using a native mutation", + "resultType": { + "object": "InsertArtist" + }, + "arguments": { + "artistId": { + "type": { + "scalar": "int" + } + }, + "name": { + "type": { + "scalar": "string" + } + } + }, + "objectTypes": { + "InsertArtist": { + "fields": { + "ok": { + "type": { + "scalar": "int" + } + }, + "n": { + "type": { + "scalar": "int" + } + } + } + } + }, + "command": { + "insert": "Artist", + "documents": [ + { + "ArtistId": "{{ artistId }}", + "Name": "{{ name }}" + } + ] + } +} +``` + +### Update +```json +{ + "name": "updateArtist", + "description": "Example of a database update using a native mutation", + "resultType": { + "object": "UpdateArtist" + }, + "arguments": { + "artistId": { + "type": { + "scalar": "int" + } + }, + "name": { + "type": { + "scalar": "string" + } + } + }, + "objectTypes": { + "UpdateArtist": { + "fields": { + "ok": { + "type": { + "scalar": "int" + } + }, + "n": { + "type": { + "scalar": "int" + } + } + } + } + }, + "command": { + "update": "Artist", + "updates": [ + { + "q": { + "ArtistId": "{{ artistId }}" + }, + "u": { + "ArtistId": "{{ artistId }}", + "Name": "{{ name }}" + } + } + ] + } +} +``` + +### Delete +```json +{ + "name": "deleteArtist", + "description": "Example of a database delete using a native mutation", + "resultType": { + "object": "DeleteArtist" + }, + "arguments": { + "artistId": { + "type": { + "scalar": "int" + } + } + }, + "objectTypes": { + "DeleteArtist": { + "fields": { + "ok": { + "type": { + "scalar": "int" + } + }, + "n": { + "type": { + "scalar": "int" + } + } + } + } + }, + "command": { + "delete": "Artist", + "deletes": [ + { + "q": { + "ArtistId": "{{ artistId }}" + } + } + ] + } +} +``` + +## Documentation + +### Name + +`"name"`: **Required** + +Represents the name of the query that is exposed in your API. + +### Description + +`"description"`: **Optional** + +Used for documentation purposes in the API. + +### Result Type + +`"resultType"`: **Required** + +Represents the result type of your command. This can refer to an existing object type from your schema or can be an object +type you write in the native query file following the structure of [Types](#types) + +### Arguments + +`"arguments"`: **Optional** + +Used if you want to accept arguments in your API for your command. Please refer to [Types](#types). Arguments are +denoted in your [command](#command) code using `"{{ argument }}"`. + +**Example:** + +```json +"arguments": { + "age": { + "type": { + "scalar": "int" + } + }, + "name": { + "type": { + "scalar": "string" + } + } +} +``` + +### Object Types + +`"objectTypes"`: **Optional** + +If you need to return a type that is not already in your schema then you can write your own. Please refer to +[Types](#types) on how to write your own object types. The only difference is those types need to be wrapped in a type +name followed by fields. + +**Example:** + +```json +"objectTypes": { + "ArtistWAlbumCount": { + "fields": { + "ArtistId": { + "type": { + "scalar": "int" + } + }, + "Name": { + "type": { + "scalar": "string" + } + }, + "AlbumCount": { + "type": { + "scalar": "int" + } + }, + "_id": { + "type": { + "scalar": "objectId" + } + } + } + } +} +``` + +### Command + +`"command"`: **Required** + +The command is almost identical to what you would write in javascript or mongosh using the [runCommand][MongoDB: +runCommand] API. The only difference is the double qouted keys to comply with JSON. For documentation on runCommand +please refer to [MongoDB][MongoDB: runCommand]. If you have arguments they need to be wrapped in double quotes and +double braces `"{{ argument }}"`. See example below. + +**Example:** + +```json +"command": { + "insert": "Artist", + "documents": [ + { + "ArtistId": "{{ artistId }}", + "Name": "{{ name }}" + } + ] +} + +``` + +## Types + +Each field in a JSON object is defined with a key specifying the name of the field. Below the key, the "type" is +specified, which can be a scalar or structural type, followed by the type name. Here are descriptions for each type: + +### Scalar Types + +- **double**: Represents a floating point number. +- **string**: Represents a sequence of characters. +- **bool**: Represents a boolean value, true or false. +- **int**: Represents an integer. +- **long**: Represents a longer form of integer. +- **decimal**: Represents a large decimal number. +- **date**: Represents a date, stored as a string in ISO format. +- **timestamp**: Represents a Unix timestamp. +- **objectId**: Represents an object identifier. + +### Structural Types +- **object**: Represents a BSON document or an embedded document. Users can define their own nested object types, +specifying the structure of these objects as required by their applications. +- **arrayOf**: Represents an array of elements, with each element being a type specified after "arrayOf". For instance, +"arrayOf": "string" means an array of strings. + +Examples: + +```json +{ + "age": { + "type": { + "scalar": "int" + } + }, + "name": { + "type": { + "scalar": "string" + } + }, + "preferences": { + "type": { + "object": "userPreferences" + } + }, + "tags": { + "type": { + "arrayOf": "string" + } + }, + "employment": { + "type": { + "object": "employmentDetails" + } + } +} +``` + +**In this example:** + +- **age** is an integer. +- **name** is a string. +- **preferences** is a complex object defined elsewhere as userPreferences, indicating a structured type defined by the +user. +- **tags** is an array consisting of strings. +- **employment** is a user-defined object type employmentDetails, which would be specified in more detail elsewhere in the +documentation. + +[DDN: collections]: https://hasura.github.io/ndc-spec/specification/schema/collections.html +[DDN: functions]: https://hasura.github.io/ndc-spec/specification/schema/functions.html +[MongoDB: runCommand]: https://www.mongodb.com/docs/manual/reference/method/db.runCommand diff --git a/docs/connectors/mongodb/native-queries/_category_.json b/docs/connectors/mongodb/native-queries/_category_.json new file mode 100644 index 000000000..2163e5c69 --- /dev/null +++ b/docs/connectors/mongodb/native-queries/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Native Queries", + "position": 2 +} diff --git a/docs/connectors/mongodb/native-queries/custom-queries.mdx b/docs/connectors/mongodb/native-queries/custom-queries.mdx new file mode 100644 index 000000000..b1f92e479 --- /dev/null +++ b/docs/connectors/mongodb/native-queries/custom-queries.mdx @@ -0,0 +1,78 @@ +--- +sidebar_position: 1 +sidebar_label: Custom Queries +description: + "Custom queries allow you to run custom aggregation pipelines on your MongoDB database. This page explains how to + configure various types of native queries in Hasura." +keywords: + - native queries + - custom queries +seoFrontMatterUpdated: false +--- + +# Custom Queries + +## Introduction + +Custom queries allow you to run custom aggregation pipelines on your MongoDB database. This allows you to run queries +that are not supported by Hasura's GraphQL engine. + +## Setup + +Native Queries can be defined by +1. Adding a `native_queries` directory if one doesn't already exist in your connector configuration directory +2. Adding a .json file following the syntax laid out in the following sections. + +Native Queries can take arguments using the `"{{argument_name}}"` syntax. Arguments must be specified along with their +type. + +## Example + +Here's an example of simple `"hello"` native query: + +### Configuration + +```json +{ + "name": "hello", + "representation": "function", + "description": "Basic test of native queries", + "arguments": { + "name": { "type": { "scalar": "string" } } + }, + "resultDocumentType": "Hello", + "objectTypes": { + "Hello": { + "fields": { + "__value": { "type": { "scalar": "string" } } + } + } + }, + "pipeline": [{ + "$documents": [{ + "__value": "{{ name }}" + }] + }] +} +``` + +This will create a query called `"hello"` which takes a single argument called `"name"` of type `string`. The +query will return an object with the key `"__value"` and the value of the argument `"hello"`. + +:::tip Valid Native Query syntax + +Check out our page on writing valid Hasura DDN [Native Query syntax](/connectors/mongodb/native-queries/syntax.mdx). + +::: + +### Usage + +With the example above, you can then use the query in your GraphQL API like this: + +```graphql +query MyQuery { + hello(name: "world") { + __value + } +} +``` diff --git a/docs/connectors/mongodb/native-queries/index.mdx b/docs/connectors/mongodb/native-queries/index.mdx new file mode 100644 index 000000000..9113beaa8 --- /dev/null +++ b/docs/connectors/mongodb/native-queries/index.mdx @@ -0,0 +1,30 @@ +--- +sidebar_position: 1 +sidebar_label: Native Queries +description: + "Native queries allow you to run custom aggregation pipelines on your MongoDB database. This allows you to run queries that + are not supported by Hasura's GraphQL engine. This page explains how to configure various types of native queries in + Hasura." +keywords: + - native queries +seoFrontMatterUpdated: false +--- + +# Native Queries + +## Introduction + +Native queries are enabled via MongoDB's [aggregation pipelines][MongoDB: pipeline], and are defined in the +MongoDB data connector's configuration. They are similar to a view but more expressive as they allow parameters +similar to functions and do not require any DDL permissions on the database. See the configuration reference on +[Native Queries](/connectors/mongodb/config.mdx#updating-with-introspection). + +## Types of Native Queries + +You can check out examples of the different types of native queries below: + +- [Custom Queries](/connectors/mongodb/native-queries/custom-queries.mdx) +- [Vector Search](/connectors/mongodb/native-queries/vector-search.mdx) + + +[MongoDB: pipeline]: https://www.mongodb.com/docs/manual/core/aggregation-pipeline \ No newline at end of file diff --git a/docs/connectors/mongodb/native-queries/syntax.mdx b/docs/connectors/mongodb/native-queries/syntax.mdx new file mode 100644 index 000000000..ae08f463a --- /dev/null +++ b/docs/connectors/mongodb/native-queries/syntax.mdx @@ -0,0 +1,409 @@ +--- +sidebar_position: 3 +sidebar_label: Syntax +description: Learn how to write native queries for MongoDB with the proper syntax in Hasura. +keywords: + - hasura + - native queries + - troubleshooting + - aggregate pipeline + - gotchas +seoFrontMatterUpdated: false +--- + +# Native Query MongoDB Syntax + +Pipeline to include in MongoDB queries. For details on how to write an aggregation pipeline +see https://www.mongodb.com/docs/manual/core/aggregation-pipeline/ + +The pipeline may include Extended JSON. + +Keys and values in the pipeline may contain placeholders of the form `{{variableName}}` +which will be substituted when the native query is executed according to the given +arguments. + +Placeholders must be inside quotes so that the pipeline can be stored in JSON format. If +the pipeline includes a string whose only content is a placeholder, when the variable is +substituted the string will be replaced by the type of the variable. For example in this +pipeline, + +```json +[{ + "$documents": "{{ documents }}" +}] +``` + +If the type of the `documents` argument is an array then after variable substitution the +pipeline will expand to: + +```json +[{ + "$documents": [/* array of documents */] +}] +``` + +## Examples + +### Collection Representation +```json +{ + "name": "ArtistWAlbumCount", + "representation": "collection", + "inputCollection": "Artist", + "description": "Artists including their album count", + "arguments": { + }, + "resultDocumentType": "ArtistWAlbumCount", + "objectTypes": { + "ArtistWAlbumCount": { + "fields": { + "ArtistId": { + "type": { + "scalar": "int" + } + }, + "Name": { + "type": { + "scalar": "string" + } + }, + "AlbumCount": { + "type": { + "scalar": "int" + } + }, + "_id": { + "type": { + "scalar": "objectId" + } + } + } + } + }, + "pipeline": [ + { + "$lookup": { + "from": "Album", + "localField": "ArtistId", + "foreignField": "ArtistId", + "as": "Albums" + } + }, + {"$unwind": "$Albums"}, + { + "$group": { + "_id": "$ArtistId", + "id": {"$first": "$_id"}, + "Name": {"$first": "$Name"}, + "AlbumCount": {"$count": {}} + } + }, + { + "$project": { + "_id": "$id", + "ArtistId": "$_id", + "Name": 1, + "AlbumCount": 1 + } + } + ] +} +``` + +### Function Representation {#example-using-function-representation} + +```json +{ + "name": "hello", + "representation": "function", + "description": "Basic test of native queries", + "arguments": { + "name": { "type": { "scalar": "string" } } + }, + "resultDocumentType": "Hello", + "objectTypes": { + "Hello": { + "fields": { + "__value": { "type": { "scalar": "string" } } + } + } + }, + "pipeline": [{ + "$documents": [{ + "__value": "{{ name }}" + }] + }] +} +``` + +## Documentation + +### Name + +| Property | Required? | +|----------|-----------| +| `"name"` | Yes | + +Represents the name of the query that is exposed in your API. + +### Representation + +| Property | Required? | +|--------------------|-----------| +| `"representation"` | Yes | + +:::tip +Using a representation of a function in MongoDB Native Queries follows the same requirements of [functions in the DDN +spec][DDN: functions]. Specifically: + +> A function is a collection which returns a single row and a single column, named __value +
+Refer to the [function example](#example-using-function-representation) above. +::: + +There are 2 options: + +1. `collection` is used here in terms of [DDN collections][DDN: collections]. +2. `function` is used here in terms of [DDN functions][DDN: functions]. + +### Input Collection + +| Property | Required? | +|---------------------|-----------| +| `"inputCollection"` | No | + +Determines how the pipeline is run. If `"inputCollection"` is present then the pipeline runs with that collection as the +starting point. It is the same as doing `db.artist.aggregate` in `mongosh`. If no `"inputCollection"` is present +then the pipeline is run with `db` as the starting point. Which is the same as doing `db.aggregate` in `mongosh`. + +### Description + +| Property | Required? | +|-----------------|-----------| +| `"description"` | No | + + +Used for documentation purposes in the API. + +### Arguments + +| Property | Required? | +|---------------|-----------| +| `"arguments"` | No | + + +Used if you want to accept arguments in your API for your pipeline. Please refer to [Types](#types). Arguments are +denoted in your [pipeline](#pipeline) code using `"{{ argument }}"`. + +**Example:** + +```json + "arguments": { + "abs": { + "type": { + "scalar": "int" + } + }, + "binarySize": { + "type": { + "scalar": "string" + } + } +``` + +### Result Document Type + +| Property | Required? | +|------------------------|-----------| +| `"resultDocumentType"` | Yes | + +Represents the result type of your pipeline. This can refer to an existing object type from your schema or can be object +types you write yourself following the structure of [Types](#types) + +A pipeline returns a stream of documents. `resultDocumentType` is the type of each individual document. + +### Object Types + +| Property | Required? | +|-----------------|-----------| +| `"objectTypes"` | No | + +If you need to return a type that is not already in your schema then you can write your own. Please refer to +[Types](#types) on how to write your own object types. The only difference is those types need to be wrapped in a type +name followed by fields. + +Object types from all configuration files occupy a shared namespace so it is important that object type names be unique +within your configuration. + +**Example:** + +```json + "objectTypes": { + "ArtistWAlbumCount": { + "fields": { + "ArtistId": { + "type": { + "scalar": "int" + } + }, + "Name": { + "type": { + "scalar": "string" + } + }, + "AlbumCount": { + "type": { + "scalar": "int" + } + }, + "_id": { + "type": { + "scalar": "objectId" + } + } + } + } + } +``` + +### Pipeline + +| Property | Required? | +|--------------|-----------| +| `"pipeline"` | Yes | + +The pipeline is almost identical to what you would write in javascript or mongosh using the [aggregate +pipeline][MongoDB: pipeline] API. The only difference is the double qouted keys to comply with JSON. For documentation +on aggregate pipelines please refer to [MongoDB][MongoDB: pipeline]. If you have arguments they need to be wrapped in +double quotes and double braces `"{{ argument }}"`. See example with arguments below. + +**Example:** without arguments + +```json + "pipeline": [ + { + "$lookup": { + "from": "Album", + "localField": "ArtistId", + "foreignField": "ArtistId", + "as": "Albums" + } + }, + {"$unwind": "$Albums"}, + { + "$group": { + "_id": "$ArtistId", + "id": {"$first": "$_id"}, + "Name": {"$first": "$Name"}, + "AlbumCount": {"$count": {}} + } + }, + { + "$project": { + "_id": "$id", + "ArtistId": "$_id", + "Name": 1, + "AlbumCount": 1 + } + } + ] +``` + +**Example:** with arguments + +```json +"pipeline": [ + { + "$documents": [ + { + "__value": { + "abs": { + "$abs": "{{ abs }}" + }, + "binarySize": { + "$binarySize": "{{ binarySize }}" + }, + "ceil": { + "$ceil": "{{ ceil }}" + }, + "floor": { + "$floor": "{{ floor }}" + }, + "divide": { + "$divide": ["{{ dividend }}", "{{ divisor }}"] + } + } + } + ] + } +] +``` + +## Types + +Each field in a JSON object is defined with a key specifying the name of the field. Below the key, the "type" is +specified, which can be a scalar or structural type, followed by the type name. Here are descriptions for each type: + +### Scalar Types + +- **double**: Represents a floating point number. +- **string**: Represents a sequence of characters. +- **bool**: Represents a boolean value, true or false. +- **int**: Represents an integer. +- **long**: Represents a longer form of integer. +- **decimal**: Represents a large decimal number. +- **date**: Represents a date, stored as a string in ISO format. +- **timestamp**: Represents a Unix timestamp. +- **objectId**: Represents an object identifier. + +### Structural Types +- **object**: Represents a BSON document or an embedded document. Users can define their own nested object types, +specifying the structure of these objects as required by their applications. +- **arrayOf**: Represents an array of elements, with each element being a type specified after "arrayOf". For instance, +"arrayOf": "string" means an array of strings. + +Examples: + +```json +{ + "age": { + "type": { + "scalar": "int" + } + }, + "name": { + "type": { + "scalar": "string" + } + }, + "preferences": { + "type": { + "object": "userPreferences" + } + }, + "tags": { + "type": { + "arrayOf": "string" + } + }, + "employment": { + "type": { + "object": "employmentDetails" + } + } +} +``` + +**In this example:** + +- **age** is an integer. +- **name** is a string. +- **preferences** is a complex object defined elsewhere as userPreferences, indicating a structured type defined by the +user. +- **tags** is an array consisting of strings. +- **employment** is a user-defined object type employmentDetails, which would be specified in more detail elsewhere in the +documentation. + +[DDN: collections]: https://hasura.github.io/ndc-spec/specification/schema/collections.html +[DDN: functions]: https://hasura.github.io/ndc-spec/specification/schema/functions.html +[MongoDB: pipeline]: https://www.mongodb.com/docs/manual/core/aggregation-pipeline diff --git a/docs/connectors/mongodb/native-queries/vector-search.mdx b/docs/connectors/mongodb/native-queries/vector-search.mdx new file mode 100644 index 000000000..f7e0fe15f --- /dev/null +++ b/docs/connectors/mongodb/native-queries/vector-search.mdx @@ -0,0 +1,214 @@ +--- +sidebar_position: 2 +sidebar_label: Vector Search +description: + "Vector search allows you to run vector similarity queries on your MongoDB database. This page explains how to + configure vector search in Hasura using native queries." +keywords: + - native queries + - vector search + - vector + - similarity + - neighbor + - nearest neighbor + - atlas +seoFrontMatterUpdated: false +--- + +# Vector Search + +Vector search allows you to run queries on vector types in your MongoDB database. This page explains how to configure +vector search in Hasura using native queries. + +:::info Prerequisites + +In order to run a vector search query, you need to have a MongoDB database on [Atlas][MongoDB: atlas]. You'll also need +data in the database which has been vectorized. The following example uses the tutorial found on +[MongoDB's](https://www.mongodb.com/products/platform/atlas-vector-search) site. + +::: + +## Example + +This uses the `sample_mflix.embedded_movies` collection to perform an approximate nearest neighbor search on a vector in +the `plot_embeddings` field. + +### Native Query configuration + +In the `native_queries` folder of our connector configuration directory add a json file named `movieSearch.json` and +enter the following: + +```json +{ + "name": "moviesSearch", + "representation": "function", + "inputCollection": "embedded_movies", + "description": "Movies approximate nearest neighbor search", + "arguments": { + "ninGenres": { + "type": { + "arrayOf": { + "scalar": "string" + } + } + }, + "inGenres": { + "type": { + "arrayOf": { + "scalar": "string" + } + } + }, + "gteYear": { + "type": { + "scalar": "int" + } + }, + "lteYear": { + "type": { + "scalar": "int" + } + }, + "numCandidates": { + "type": { + "scalar": "int" + } + }, + "limit": { + "type": { + "scalar": "int" + } + } + }, + "resultDocumentType": "MoviesSearch", + "objectTypes": { + "MoviesSearch": { + "fields": { + "__value": { + "type": { + "arrayOf": { + "object": "MoviesSearchOutput" + } + } + } + } + }, + "MoviesSearchOutput": { + "fields": { + "title": { + "type": { + "scalar": "string" + } + }, + "plot": { + "type": { + "scalar": "string" + } + }, + "genres": { + "type": { + "arrayOf": { + "scalar": "string" + } + } + }, + "year": { + "type": { + "scalar": "int" + } + }, + "score": { + "type": { + "scalar": "double" + } + } + } + } + }, + "pipeline": [ + { + "$vectorSearch": { + "index": "vector-search-tutorial", + "path": "plot_embedding", + "filter": { + "$and": [ + { + "genres": { + "$nin": "{{ ninGenres }}", + "$in": "{{ inGenres }}" + } + }, { + "year": { + "$gte": "{{ gteYear }}", + "$lte": "{{ lteYear }}" + } + } + ] + }, + "queryVector": [-0.020156775, -0.024996493, 0.010778184, -0.030058576, -0.03309321, 0.0031229265, -0.022772837, 0.0028351594, 0.00036870153, -0.02820117, 0.016245758, 0.0036232488, 0.0020519753, -0.0076454473, 0.0073380596, -0.007377301, 0.039267123, -0.013433489, 0.01428371, -0.017279103, -0.028358135, 0.0020160044, 0.00856761, 0.009653277, 0.0107912645, -0.026683854, 0.009594415, -0.020182934, 0.018077003, -0.015709465, 0.003310956, 0.0014878864, -0.015971072, -0.002411684, -0.029561523, -0.030450987, -0.013106481, -0.005385822, -0.018652538, 0.012642129, -0.005189617, 0.018835662, -0.0048102876, -0.0261214, -0.016167276, -0.007972456, 0.0023381072, -0.010058766, -0.009012341, 0.008358325, 0.018665617, 0.02163485, -0.012975678, -0.010745483, -0.002571918, -0.014479915, 0.007226877, 0.015003128, 0.013165343, -0.028279653, 0.0053727417, -0.020588424, -0.017383745, 0.023518417, 0.01262905, -0.011922712, 0.007638907, -0.0073249796, -0.014859244, -0.00001101736, 0.017043658, 0.010111088, 0.0074623227, 0.009555174, 0.008338705, -0.002240005, -0.0010603234, -0.004973792, 0.003391073, 0.021543289, 0.013341927, 0.0005980159, 0.010693162, 0.005336771, 0.016062634, 0.005768421, 0.005186347, 0.039790336, 0.0021942237, -0.0026275094, 0.010431555, 0.0042151334, -0.0050359233, 0.025768232, -0.021451725, 0.01833861, -0.01836477, -0.013433489, 0.030006256, -0.014793842, 0.017475309, 0.0020585153, -0.012975678, -0.017266022, -0.01593183, -0.014257549, 0.0010676811, -0.007887433, -0.0045911926, 0.00012303676, -0.0014976967, 0.03552615, 0.0065630507, -0.037435878, 0.011929252, -0.00939167, 0.016768971, 0.01223664, 0.007789331, -0.037200432, 0.013145722, 0.00896002, 0.021857215, 0.010333453, 0.021582529, -0.007089534, -0.007154935, -0.02485261, 0.0040254686, -0.00088864425, 0.023466095, -0.020719228, -0.006690584, -0.021006994, -0.018286288, 0.025545865, -0.0096598165, 0.008803056, -0.023021365, -0.040078104, 0.015408617, 0.017043658, -0.011242535, 0.0063537657, -0.026618453, 0.0071614753, -0.014623798, 0.00067322777, -0.00083427917, -0.028070368, 0.03714811, -0.004529061, 0.0054087127, 0.0028727653, 0.008384486, 0.010026066, -0.006190262, -0.0002493436, 0.0029953935, -0.026226042, -0.018417092, 0.009941043, 0.0036494094, -0.00982332, 0.013551212, 0.02574207, -0.0022645304, -0.0006004685, 0.012805633, -0.024303235, 0.008194821, -0.014179068, -0.02977081, 0.003095131, -0.0015941641, 0.029953934, 0.0052680993, 0.025388902, -0.031392768, -0.021386323, 0.014898485, 0.022419669, 0.00897964, 0.013243824, 0.006854088, 0.0066415328, -0.003839074, -0.01877026, 0.021216279, -0.015055449, -0.0015508354, 0.013211124, -0.008783435, 0.0052157775, -0.68938524, -0.01221702, -0.04125533, -0.016232677, 0.020039052, -0.0026422248, -0.0037050007, 0.0064682183, -0.0047579664, 0.0032749851, -0.0035382267, 0.031942144, -0.00035643874, -0.011628405, -0.043086577, -0.0196074, -0.0066088317, -0.014872325, 0.028331975, 0.010294212, -0.013930541, 0.031994462, -0.018626377, 0.017462227, 0.026343765, -0.010274592, 0.0046827546, -0.029430721, -0.011746128, 0.0024362097, 0.0023054064, 0.0027730279, -0.002406779, 0.003917556, 0.059436977, 0.008665713, -0.0018901062, 0.06037876, 0.017880797, 0.05185039, 0.0067102043, -0.020300657, 0.005604917, 0.018704858, 0.012073136, 0.0144145135, 0.012413224, -0.0074819434, 0.015801027, -0.0061412104, 0.008613391, -0.0039077457, -0.0036232488, 0.008469507, 0.014087505, 0.0124066835, 0.019267311, -0.002573553, 0.005055544, -0.009417831, -0.009103903, 0.011150973, -0.012046975, 0.0058567133, -0.0053727417, 0.018260127, -0.005588567, 0.015591742, 0.007495024, -0.02567667, 0.024211673, 0.021386323, -0.012890656, -0.016114954, 0.009515933, 0.009679437, 0.025532786, -0.0076454473, -0.02575515, 0.008319084, -0.0068410076, -0.017082898, -0.026173722, -0.0049901423, 0.01918883, -0.008646091, -0.031759016, 0.014820003, 0.011850771, 0.01836477, 0.012700991, -0.0011437106, 0.005058814, 0.0151993325, -0.0060692686, 0.027416352, 0.0037344315, 0.0013546307, 0.018325528, -0.03152357, -0.008809595, 0.014649959, -0.008345244, 0.0066415328, -0.005523165, 0.0043492066, -0.0015892589, 0.0048855, 0.034453563, -0.03837766, 0.0068410076, -0.0042151334, -0.0067429054, 0.0055689462, -0.011733048, -0.0212032, 0.016847452, -0.0022220195, 0.0059351954, -0.00449963, 0.02251123, -0.01020265, 0.023361452, -0.0032455544, 0.016180357, 0.0049443613, -0.0064747585, -0.03259616, 0.012321662, 0.020104453, 0.009954124, -0.019411195, 0.0048102876, -0.000392614, 0.012184318, 0.0044276887, 0.005634348, -0.020562263, 0.015722545, -0.005179807, -0.0067952266, 0.0027861083, 0.0024198592, -0.0020585153, 0.0018525004, -0.045100946, -0.010176489, -0.012956058, 0.0013497255, 0.0105361985, 0.003796563, -0.0106016, -0.013126101, 0.0050359233, 0.015003128, -0.0075800456, -0.015722545, -0.01755379, -0.00978408, -0.02940456, 0.017606111, 0.016612006, -0.016912855, 0.025441224, 0.0054741143, 0.00448001, 0.009470152, 0.015382457, -0.008332164, -0.019123428, 0.024564842, 0.016860534, 0.008286383, -0.007141855, 0.006559781, 0.016625088, -0.01840401, -0.011602244, -0.00489858, -0.0073184394, -0.008809595, -0.0018459603, -0.01629808, -0.005542786, 0.0064257076, 0.010379234, 0.014663039, 0.034872133, -0.013355007, 0.027285548, 0.011654565, -0.004032009, 0.02323065, -0.02653997, -0.0009941043, 0.002946342, 0.010667001, 0.008345244, 0.018626377, 0.04821406, 0.031392768, 0.010281132, 0.026069079, 0.002735422, 0.01182461, -0.01593183, 0.006585941, -0.010071847, 0.024564842, -0.0025261368, 0.004293615, -0.0068606283, -0.0066448026, -0.0074100015, -0.0014347476, 0.021530207, -0.010418476, 0.018495573, -0.0034924455, -0.014165987, -0.004784127, -0.012472086, 0.004417878, -0.0030313642, -0.010084927, -0.010954768, 0.01508161, 0.0010047321, 0.0042347535, -0.03345946, -0.00027346043, 0.014793842, -0.019882087, 0.012772933, 0.021490967, 0.0031932332, 0.0093589695, 0.00090172456, 0.0048102876, 0.0070045115, -0.0045584915, 0.015840268, 0.024342475, -0.0091300635, 0.0039796876, 0.003796563, 0.025022654, -0.008103259, -0.025022654, 0.03021554, -0.008201361, -0.0070502926, 0.0011821339, 0.021072397, 0.004849529, -0.02495725, 0.012184318, 0.0019228071, -0.007226877, 0.020562263, 0.018861823, -0.0017593032, 0.01345965, 0.0022727058, 0.003023189, -0.026971621, -0.0030558899, 0.017723834, -0.01998673, -0.010608139, 0.011491061, -0.025179617, 0.0069652707, 0.003924096, 0.021177039, 0.0045650317, -0.0009973744, 0.007586586, -0.004032009, -0.008129419, -0.010091467, -0.04279881, 0.019790525, 0.01595799, 0.0044309585, -0.0033747226, -0.018665617, -0.012818714, -0.016206518, 0.014113666, -0.0020912162, 0.01427063, -0.020248337, -0.0112752365, -0.020588424, -0.011039791, 0.008744194, -0.015147011, 0.0022269245, -0.010438096, -0.0017772885, -0.028750544, -0.008861917, -0.016991336, 0.033668745, 0.034636687, 0.009888723, 0.0023953337, 0.006991431, -0.003346927, 0.003103306, -0.0044571194, 0.011249076, 0.0033779927, 0.00012446742, -0.0027027212, -0.025859794, -0.011942333, 0.02694546, 0.028227331, 0.0064289775, -0.03385187, -0.020719228, 0.00489531, 0.10663077, 0.041752383, -0.021700252, -0.008103259, 0.0049574412, -0.01675589, -0.020182934, -0.006585941, 0.007684688, -0.002859685, 0.027023941, 0.00856107, 0.0037017306, 0.016978256, 0.025885954, -0.010372694, 0.0025964435, 0.011706887, 0.021360163, -0.021674091, -0.024983412, 0.0034074234, 0.0032030435, 0.022262705, -0.01266829, -0.002249815, 0.032779284, -0.0034303141, -0.016101874, -0.005156916, -0.0212032, 0.005362931, 0.009077743, -0.013917461, -0.0017315074, 0.010980929, -0.019450437, 0.013865139, 0.028227331, -0.008757275, -0.0033649125, -0.012857955, 0.011039791, 0.009764459, 0.00029594224, -0.026317604, 0.025048813, 0.037749805, -0.025807472, -0.005425063, 0.021791814, -0.010012985, -0.00066995766, -0.016952096, 0.0031147513, -0.016598927, 0.0084368065, 0.004787397, -0.0064355177, 0.0015164997, -0.021216279, -0.023845425, 0.013969782, -0.011255615, 0.0042576445, -0.024250913, -0.009908343, -0.02289056, -0.023361452, -0.010987469, -0.013394248, 0.0032553647, -0.019018786, 0.021438645, 0.029587684, -0.010490417, 0.01263559, -0.018417092, -0.008731114, 0.01875718, -0.0072399573, -0.029090632, -0.017736914, -0.04031355, -0.019712042, 0.012772933, -0.030320182, -0.022341188, -0.02041838, 0.011752668, 0.028829027, -0.017043658, 0.024996493, 0.006334145, -0.0024263994, -0.0077370093, 0.017802317, 0.017396826, 0.030398665, 0.011464901, 0.03016322, -0.014558396, -0.0036690298, -0.009954124, -0.006703664, -0.00035705187, -0.014519156, 0.0075342646, -0.00896656, 0.040078104, 0.024420958, -0.016886694, -0.00092543266, -0.0017494928, 0.01672973, 0.016533526, 0.002648765, 0.0187441, -0.0055460557, 0.004735076, 0.03186366, 0.0003435628, 0.007495024, 0.023453014, -0.012504786, -0.0074557825, -0.0027844731, -0.04570264, 0.010477337, 0.0030101088, -0.015670223, 0.03351178, -0.020261416, 0.00050849747, -0.009653277, -0.023466095, -0.007396921, -0.011909632, 0.003436854, -0.02979697, -0.039031677, -0.014584557, 0.0019555078, 0.0042216736, -0.0060594585, -0.023400694, -0.00023462824, -0.017763074, -0.016180357, 0.0132372845, -0.020496862, -0.007390381, -0.0058697937, -0.0096598165, 0.0039796876, -0.019306554, -0.012622509, -0.0012287326, 0.010863206, 0.024368636, 0.027730279, 0.016795132, 0.019908248, -0.006343955, 0.0014592733, -0.005425063, 0.019450437, 0.004532331, -0.031889822, 0.008476048, 0.019712042, -0.00047906674, -0.0028286192, 0.011883471, -0.012426305, 0.0041497317, 0.001756033, -0.0013603533, -0.008031317, -0.010281132, -0.0071222344, -0.026330685, -0.007920134, -0.026866978, -0.03026786, -0.0015328501, 0.027442513, -0.005922115, 0.005186347, 0.003436854, 0.036703378, -0.0053204205, 0.013165343, 0.0016939015, -0.0041431915, -0.017213702, -0.012439385, -0.015212413, 0.014532236, 0.0093589695, -0.0053400407, 0.017422987, -0.028881347, -0.014179068, 0.011307937, 0.040104263, -0.007593126, -0.000631943, -0.0003404971, -0.0055198953, -0.00063030794, -0.004852799, -0.0024214943, -0.029718488, 0.023322212, 0.011079031, 0.012988758, 0.0071614753, -0.034034993, -0.01551326, 0.004012388, 0.006442058, 0.032386873, 0.0076519875, 0.0465921, 0.01757995, -0.0135381315, -0.016978256, 0.024983412, 0.0003280299, 0.0026209692, 0.022380428, -0.010640841, 0.0027648527, -0.007959375, -0.005922115, 0.0075342646, -0.03597088, -0.018874902, 0.03510758, -0.015356296, 0.004597733, -0.0015328501, -0.019947488, -0.013446569, 0.020614585, -0.0056016473, 0.035186063, 0.0005248479, -0.030712591, -0.019136509, 0.004202053, -0.010339993, 0.014754602, 0.0072922786, -0.015460939, 0.027494833, -0.02974465, -0.0033616424, 0.0105819795, -0.028881347, 0.01720062, -0.0073707607, 0.0054479535, -0.0019522378, -0.018103164, -0.009110443, -0.024630243, 0.005624538, 0.01879642, -0.019345794, -0.0027681228, -0.015971072, 0.022354268, -0.0038194535, 0.018901063, -0.017357586, -0.02493109, 0.006703664, -0.0021173768, -0.005667049, -0.004535601, -0.016441964, 0.0034172337, -0.02447328, -0.003310956, -0.02078463, -0.011589164, 0.013263445, -0.014728441, -0.0187441, -0.019476596, 0.013224204, 0.015238573, -0.012380524, 0.00019058435, 0.010778184, 0.025022654, -0.036127847, 0.01470228, -0.007671608, 0.032857765, 0.002982313, 0.009829861, 0.0072203367, -0.0028237142, 0.025990596, -0.029012151, 0.0016955365, 0.012033895, -0.0049901423, -0.013629694, 0.0072464976, 0.0012704261, 0.0018868363, 0.017043658, 0.00448001, -0.009555174, -0.016520444, 0.02570283, -0.00939167, 0.01998673, 0.002001289, -0.023662299, 0.0041072206, -0.024839528, -0.007396921, -0.0034793653, -0.032020625, -0.0036003583, -0.010719323, 0.022995204, -0.01757995, -0.0043851775, -0.023884665, -0.018430172, -0.009018881, 0.00091562246, -0.0055689462, -0.012537487, 0.016455043, 0.03264848, 0.018560974, 0.014623798, 0.0025555675, -0.0060986993, 0.0058272826, -0.008462967, -0.012720612, -0.0042576445, -0.027207067, 0.014152907, -0.0029610575, 0.010241891, -0.011222915, -0.01140604, -0.022197304, -0.003433584, -0.0056899395, 0.004372097, 0.061896075, -0.005846903, -0.011863851, 0.004535601, -0.0074819434, 0.016847452, -0.0012647035, 0.021085477, 0.02409395, -0.030137058, -0.0012197399, 0.009607496, -0.008220982, -0.007893973, -0.007893973, 0.007972456, 0.010012985, 0.009143144, 0.0044734697, 0.015264734, -0.0032520946, 0.002208939, 0.011968493, -0.0012998568, -0.0114322, -0.056454662, -0.013217663, 0.0017593032, -0.00244275, -0.021399405, -0.010732403, 0.00694565, 0.0033207664, 0.0025539326, 0.01102671, -0.012589809, 0.010706242, -0.012413224, 0.01427063, -0.000049970913, -0.0056016473, 0.027965724, 0.018652538, -0.009535554, 0.0068867886, 0.004699105, -0.001245083, -0.009071202, -0.0032946058, -0.03756668, 0.034453563, -0.00408106, 0.013361547, -0.0065107294, 0.009300108, -0.016415803, 0.0059973267, -0.017422987, 0.0048822295, 0.022158062, -0.025611266, 0.01022227, -0.0061771814, -0.014218308, -0.00044636594, -0.019110348, -0.013747416, -0.013629694, -0.021896457, -0.0051634563, -0.020509942, -0.018731019, 0.0043328563, -0.032386873, -0.023086766, 0.0196074, 0.20614585, -0.014649959, -0.009712138, 0.01345965, -0.010928608, 0.0196074, 0.015814107, 0.017383745, -0.0024656404, 0.021399405, 0.013668935, -0.0063864663, -0.0015303975, -0.0012924991, -0.0030575248, -0.015539421, -0.009692517, -0.012190859, -0.02287748, 0.002936532, 0.00069325697, 0.013158802, -0.0070110518, -0.013629694, 0.01585335, -0.019829765, 0.013747416, 0.016036473, 0.011693806, 0.0071483953, -0.010156869, -0.013799738, -0.00034703725, -0.010706242, -0.02289056, 0.0039339066, -0.0015835363, -0.014532236, 0.012445925, -0.00009779583, 0.0053335004, 0.0055329753, -0.005281179, -0.007475403, 0.00040385488, -0.012942977, -0.015277814, 0.012956058, 0.00006162057, 0.007056833, -0.02571591, -0.018731019, -0.0061771814, 0.034427404, 0.0010570535, 0.0079528345, 0.024172433, 0.021386323, -0.019803606, -0.006821387, -0.011262156, 0.026605371, -0.0036951904, -0.008207901, -0.019698963, 0.042981934, -0.026212962, 0.00856761, 0.015173172, 0.0024149541, -0.0008036222, -0.005752071, -0.02898599, -0.008443347, -0.0064224373, -0.014479915, 0.036467932, -0.00086820626, 0.026396086, 0.002001289, -0.0074361623, -0.0086918725, -0.007835112, 0.021464806, 0.0008984545, -0.02489185, 0.019515838, 0.026644614, -0.0137212565, 0.00448982, 0.004211863, -0.022380428, -0.014100585, -0.01629808, 0.0074884836, 0.02652689, 0.011634945, 0.049626734, -0.023583818, -0.0021958589, -0.015735626, 0.02733787, 0.0036428692, -0.031261966, -0.012674831, 0.006196802, -0.009535554, 0.016886694, 0.010771644, -0.021490967, 0.014100585, -0.007063373, 0.00043778197, -0.012151618, -0.0058894143, 0.009182385, -0.005768421, -0.013995943, 0.004725266, -0.01347273, -0.020797709, -0.018037762, 0.020274498, 0.011595704, 0.0017364125, -0.02248507, 0.005954816, 0.0062196925, -0.014257549, -0.025127295, 0.015356296, 0.005179807, 0.021726413, -0.0034499345, -0.017082898, 0.019803606, 0.005209238, 0.0005939283, -0.0035807376, -0.011661106, 0.006559781, 0.0033207664, 0.0017233322, -0.00059924216, -0.000341519, -0.0140221035, 0.00084286317, -0.003306051, -0.005634348, -0.00816212, -0.009319728, -0.024447119, -0.014950806, -0.024564842, 0.0137212565, -0.010084927, 0.000044886958, -0.0033943432, 0.0025359471, 0.012478625, -0.023086766, 0.014519156, 0.020876192, -0.023282971, -0.0030804155, -0.014545316, -0.16805595, 0.01262905, 0.020719228, -0.012413224, 0.026592292, -0.0024198592, 0.041072205, 0.002658575, -0.013708176, -0.0068867886, -0.0018639456, 0.000031627806, -0.043452825, -0.028018046, -0.0105819795, 0.01266829, -0.009450532, 0.008292923, 0.0058534434, -0.006782146, 0.032229908, 0.0005955633, -0.0023103117, 0.003140912, 0.00037687673, -0.0049247406, -0.008070557, 0.017279103, -0.012759852, -0.011608784, -0.019450437, 0.016167276, 0.02248507, 0.030529467, 0.015905669, 0.0061150496, -0.016834373, 0.017344505, 0.006667693, -0.005461034, 0.0066742334, 0.01998673, 0.024591003, -0.007717389, 0.0096598165, 0.03225607, 0.018626377, -0.020248337, 0.0017740185, 0.012589809, 0.0014927916, -0.040235065, 0.01713522, 0.016206518, 0.017776156, 0.024734886, 0.0040516295, -0.009627116, 0.002001289, -0.010496957, -0.0121058365, -0.017266022, 0.008279843, -0.02122936, -0.01349889, -0.02251123, 0.004820098, -0.000071533, -0.022628954, 0.015238573, -0.01833861, -0.016572766, -0.0031523572, -0.008064018, 0.019973649, 0.0089207785, -0.03228223, 0.0040647094, -0.004784127, -0.0017920039, -0.0013775212, 0.047246117, 0.0030804155, -0.010660461, 0.02982313, 0.006088889, -0.019371955, -0.024447119, -0.011687267, -0.013708176, 0.017187541, -0.018286288, 0.019267311, 0.0011960318, 0.0046271635, 0.016886694, 0.0069129495, 0.00029062838, 0.013629694, -0.016494283, -0.017069818, 0.0058240127, 0.013943622, 0.001675916, 0.01347273, 0.023335291, 0.008129419, 0.0047187256, 0.032099105, 0.0007701039, 0.0068344674, 0.0004672127, -0.00610851, 0.026396086, -0.010738943, 0.024591003, 0.008220982, -0.019908248, 0.024682565, -0.009404751, 0.0594893, -0.009731758, -0.022628954, 0.013865139, -0.016049553, 0.0033371167, -0.107572556, -0.022341188, 0.008050937, -0.0089731, 0.004983602, 0.010771644, -0.013034539, -0.013368088, -0.0071287747, 0.0091758445, -0.017409906, -0.022118822, -0.011170594, -0.010908987, 0.050490037, 0.014584557, 0.018312449, 0.0014968792, -0.0057161, 0.024342475, -0.02699778, 0.020091372, -0.00094587065, -0.021347083, -0.003711541, 0.0016677409, -0.030738752, 0.040208906, 0.008109799, -0.017527629, -0.0009058122, 0.017776156, 0.0052779093, -0.0046206233, 0.0067952266, -0.01226934, -0.009162764, -0.01595799, 0.021582529, -0.027390191, -0.00011210243, -0.003145817, 0.01672973, -0.009999905, 0.003832534, -0.01793312, -0.0004868332, 0.027573315, 0.001756033, -0.012112376, -0.009718678, 0.0025473924, -0.027547155, -0.019084187, 0.010693162, 0.025558947, -0.02168717, -0.0068802484, -0.010869746, -0.028698223, -0.0051634563, -0.012131997, -0.014963887, 0.022210384, 0.01510777, -0.0026504, -0.013577373, 0.0058599836, 0.011281776, -0.0009393305, -0.00204053, 0.030110897, -0.029326078, 0.006491109, -0.01671665, 0.0006049648, -0.024342475, -0.008325624, 0.03722659, -0.007710849, -0.0055656764, -0.02043146, -0.015317055, -0.015212413, 0.002815539, 0.022262705, 0.00818828, 0.021778734, -0.0037409717, -0.02485261, 0.0033779927, 0.013217663, -0.0059319255, -0.018940303, 0.02409395, 0.015761785, -0.009672897, 0.011301396, -0.011582624, 0.0029725027, -0.015343216, -0.00735114, -0.075761214, 0.016821291, 0.0028040938, 0.0017233322, 0.01595799, -0.0054741143, -0.007096074, -0.011641486, -0.003554577, 0.009829861, -0.037828285, 0.024983412, 0.003793293, -0.010895907, -0.011916172, -0.017893879, 0.029640006, 0.0027452323, 0.004977062, 0.0138913, 0.0132830655, 0.010725862, 0.014205228, -0.003839074, 0.020470701, 0.0048626093, -0.010967849, 0.035343025, -0.004568302, -0.007665068, 0.0040091183, -0.02367538, -0.006821387, 0.012112376, -0.0012475356, -0.02041838, -0.030869557, -0.004865879, 0.036127847, 0.019528918, 0.00087147637, 0.0016366751, -0.006072539, -0.012380524, -0.016886694, 0.0014224849, 0.0058632535, 0.0053138803, 0.024525601, -0.008227522, 0.016167276, 0.021373244, -0.019855926, -0.011602244, -0.012223559, 0.009116983, 0.00448001, 0.0027027212, 0.0112294555, -0.025048813, 0.005958086, 0.005578757, 0.012040435, -0.019528918, -0.008096718, -0.023439934, 0.00047497914, 0.0073315194, 0.025061894, -0.016455043, 0.003992768, 0.002038895, -0.0003484679, 0.004444039, -0.014846164, 0.0018263398, 0.017305264, -0.0047154557, -0.006729825, 0.011288317, -0.009764459, -0.03220375, -0.015369376, 0.009594415, 0.031078842, 0.020967754, -0.007802411, 0.022354268, -0.010778184, 0.01833861, 0.004581382, 0.0072399573, 0.010673542, -0.012112376, -0.023073684, 0.0066448026, -0.027887244, 0.0063504954, 0.012956058, 0.032151427, -0.018103164, 0.0048855, -0.018286288, -0.036938824, -0.012354363, 0.020039052, 0.004921471, -0.03790677, 0.0212686, 0.02982313, 0.015434778, 0.0041039507, -0.016245758, 0.012171238, -0.006415897, 0.0072464976, -0.0024362097, -0.025218857, -0.021399405, 0.036860343, 0.0056572384, 0.017004417, 0.03432276, -0.013825899, 0.028724384, 0.008528369, 0.018652538, -0.02443404, -0.025637427, 0.006497649, -0.015447859, 0.01917575, -0.016520444, -0.008678793, -0.021072397, 0.015840268, -0.006324335, 0.025925195, -0.03594472, 0.0384823, 0.01308032, 0.0054217926, 0.00448328, -0.027207067, -0.016847452, 0.0036003583, 0.01061468, -0.019816685, -0.004659864, 0.023387613, -0.005461034, 0.004326316, 0.0037278912, -0.007540805, 0.00860031, 0.0015524705, 0.020039052, -0.0028367946, 0.0049509015, 0.009162764, 0.009705598, 0.013982862, 0.004852799, 0.0061869915, -0.0083910255, 0.012975678, -0.034558207, -0.029064473, -0.03058179, -0.019450437, 0.01062122, -0.014179068, -0.010012985, 0.007874353, -0.014126746, -0.009731758, -0.03398267, -0.000115883464, -0.0029725027, -0.024290156, 0.012864495, -0.00937859, -0.035264544, 0.0027959184, 0.012982218, -0.012609429, 0.0065270797, 0.010712783], + "numCandidates": "{{ numCandidates }}", + "limit": "{{ limit }}" + } + }, + { + "$project": { + "_id": 0, + "title": 1, + "genres": 1, + "plot": 1, + "year": 1, + "score": { + "$meta": "vectorSearchScore" + } + } + }, + { + "$group": { + "_id": null, + "__value": { + "$addToSet": { + "title": "$title", + "genres": "$genres", + "plot": "$plot", + "year": "$year", + "score": "$score" + } + } + } + }, + { + "$project": { + "_id": 0, + "__value": 1 + } + } + ] +} +``` + +### Usage + +Now you can use the flexibility of Hasura's GraphQL API to search your vectors in many ways. + +#### Search movies + +```graphql +query MyQuery { + moviesSearch( + ninGenres: ["Drama", "Western", "Crime"] + inGenres: ["Action", "Adventure", "Family"] + gteYear: 1960 + lteYear: 2000 + numCandidates: 200 + limit: 2 + ) { + genres + plot + score + year + title + } +} +``` + +[MongoDB: atlas]: https://www.mongodb.com/atlas/database diff --git a/docs/connectors/overview.mdx b/docs/connectors/overview.mdx index 22c024451..449b28a7e 100644 --- a/docs/connectors/overview.mdx +++ b/docs/connectors/overview.mdx @@ -167,14 +167,14 @@ what's coming up on the roadmap. - +
MongoDB
+ +
diff --git a/docs/connectors/typescript.mdx b/docs/connectors/typescript.mdx index 0eabeaad4..7c766f31e 100644 --- a/docs/connectors/typescript.mdx +++ b/docs/connectors/typescript.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 8 sidebar_label: TypeScript description: "Explore how to add custom business logic to your Hasura projects through the TypeScript data connector. Integrate diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 57a466e7b..c96d7bb23 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -179,6 +179,7 @@ const config: Config = { prism: { theme: prismThemes.github, darkTheme: prismThemes.dracula, + additionalLanguages: ['JSON'], }, } satisfies Preset.ThemeConfig, markdown: {