Data Connector Links
Introduction
A DataConnectorLink
is a used to specify the URLs and NDC schema of a data connector
allowing to link it to models and commands. It
can be used to connect to various types of data connectors on different data sources, like SQL databases, NoSQL
databases, REST APIs, GraphQL APIs, files, and more.
How DataConnectorLinks work
Lifecycle
A DataConnectorLink
can be created using the CLI. Out of convenience, the
CLI will scaffold this file automatically for you when
initializing a new connector.
A DataConnectorLink
belongs to a single subgraph and represents a connection
to a data source. It is used to link the data source to the subgraph's models, commands, and relationships. The contents
can be updated using the CLI. This will introspect the data source and
update the schema of the data connector.
Any time your data source schema changes, you should update the DataConnectorLink
to reflect those changes. This will
ensure that the schema of the data connector is up to date and that the data connector can be used to serve requests.
This configuration is then used to generate the metadata representing collections present in the data source.
The example we linked above is for adding all models, commands, and relationships present in a data source. However, you
can add each resource individually after updating the DataConnectorLink
configuration:
To make a new data connector link and it's cascading metadata available in your supergraph, you'll need to create a new build using the CLI after adding your resources.
Examples
kind: DataConnectorLink
version: v1
definition:
name: data_connector
url:
singleUrl:
value: http://data_connector:8100
headers: {}
schema:
version: v0.1
schema:
scalar_types: {}
object_types: {}
collections: []
functions: []
procedures: []
capabilities:
version: 0.1.3
capabilities:
query:
nested_fields: {}
variables: {}
mutation: {}
Field | Description | Reference |
---|---|---|
kind | Specifies the type of configuration, in this case, DataConnectorLink. | DataConnectorLink |
version | The version of the DataConnectorLink configuration, which is v1 . | DataConnectorLinkV1 |
definition.name | The name given to this data connector configuration. | DataConnectorName |
definition.url.singleUrl.value | The URL used to access the data connector. | DataConnectorUrlV1 |
definition.headers | A key-value map of HTTP headers to be sent with each request to the data connector. | HttpHeaders |
definition.schema.version | The version of the schema that the data connector is using. | SchemaAndCapabilitiesV01 |
definition.schema.schema[] | The schema of the data connector, representing various types, collections, functions, and procedures. | SchemaAndCapabilitiesV01 |
definition.schema.capabilities.version | The version of the capabilities that the data connector supports. | SchemaAndCapabilitiesV01 |
definition.schema.capabilities.capabilities.query | The query capabilities of the data connector. | SchemaAndCapabilitiesV01 |
definition.schema.capabilities.capabilities.mutation | The mutation capabilities of the data connector. | SchemaAndCapabilitiesV01 |
Metadata structure
DataConnectorLink
Definition of a data connector, used to bring in sources of data and connect them to OpenDD models and commands.
Key | Value | Required | Description |
---|---|---|---|
kind | DataConnectorLink | true | |
version | v1 | true | |
definition | DataConnectorLinkV1 | true | Definition of a data connector - version 1. |
Example:
kind: DataConnectorLink
version: v1
definition:
name: data_connector
url:
singleUrl:
value: http://data_connector:8100
headers: {}
schema:
version: v0.1
schema:
scalar_types: {}
object_types: {}
collections: []
functions: []
procedures: []
capabilities:
version: 0.1.3
capabilities:
query:
nested_fields: {}
variables: {}
mutation: {}
DataConnectorLinkV1
Definition of a data connector - version 1.
Key | Value | Required | Description |
---|---|---|---|
name | DataConnectorName | true | The name of the data connector. |
url | DataConnectorUrlV1 | true | The url(s) to access the data connector. |
headers | HttpHeaders | false | Key value map of HTTP headers to be sent with each request to the data connector. This is meant for protocol level use between engine and the data connector. |
schema | SchemaAndCapabilitiesV01 | true | The schema of the data connector. This schema is used as the source of truth when serving requests and the live schema of the data connector is not looked up. |
argumentPresets | [DataConnectorArgumentPreset] | false | Argument presets that applies to all functions and procedures of this data connector. Defaults to no argument presets. |
responseHeaders | ResponseHeaders / null | false | HTTP response headers configuration that is forwarded from a data connector to the client. |
ResponseHeaders
Configuration of what HTTP response headers should be forwarded from a data connector to the client in HTTP response.
Key | Value | Required | Description |
---|---|---|---|
headersField | DataConnectorColumnName | true | Name of the field in the NDC function/procedure's result which contains the response headers |
resultField | DataConnectorColumnName | true | Name of the field in the NDC function/procedure's result which contains the result |
forwardHeaders | [string] | true | List of actual HTTP response headers from the data connector to be set as response headers |
DataConnectorColumnName
The name of a column in a data connector.
Value: string
DataConnectorArgumentPreset
An argument preset that can be applied to all functions/procedures of a connector
Key | Value | Required | Description |
---|---|---|---|
argument | ArgumentName | true | |
value | DataConnectorArgumentPresetValue | true |
DataConnectorArgumentPresetValue
Key | Value | Required | Description |
---|---|---|---|
httpHeaders | HttpHeadersPreset | true | HTTP headers that can be preset from request |
HttpHeadersPreset
Configuration of what HTTP request headers should be forwarded to a data connector.
Key | Value | Required | Description |
---|---|---|---|
forward | [string] | true | List of HTTP headers that should be forwarded from HTTP requests |
additional | AdditionalHttpHeaders | true | Additional headers that should be forwarded, from other contexts |
AdditionalHttpHeaders
Additional headers that should be forwarded, from other contexts
Key | Value | Required | Description |
---|---|---|---|
<customKey> | ValueExpression | false |
ValueExpression
An expression which evaluates to a value that can be used in permissions and various presets.
Must have exactly one of the following fields:
Key | Value | Required | Description |
---|---|---|---|
literal | false | ||
sessionVariable | string | false |
ArgumentName
The name of an argument.
Value: string
SchemaAndCapabilitiesV01
The schema of the data connector. This schema is used as the source of truth when serving requests and the live schema of the data connector is not looked up.
Key | Value | Required | Description |
---|---|---|---|
version | v0.1 | true | |
schema | Schema Response | true | |
capabilities | Capabilities Response | true |
HttpHeaders
Key value map of HTTP headers to be sent with an HTTP request. The key is the header name and the value is a potential reference to an environment variable.
Key | Value | Required | Description |
---|---|---|---|
<customKey> | EnvironmentValue | false | Either a literal string or a reference to a Hasura secret |
DataConnectorUrlV1
The url(s) to access the data connector.
Must have exactly one of the following fields:
Key | Value | Required | Description |
---|---|---|---|
singleUrl | EnvironmentValue | false | |
readWriteUrls | ReadWriteUrls | false |
ReadWriteUrls
Key | Value | Required | Description |
---|---|---|---|
read | EnvironmentValue | true | |
write | EnvironmentValue | true |
EnvironmentValue
Either a literal string or a reference to a Hasura secret
Must have exactly one of the following fields:
Key | Value | Required | Description |
---|---|---|---|
value | string | false | |
valueFromEnv | string | false |
DataConnectorName
The name of a data connector.
Value: string
DataConnectorScalarRepresentation
The representation of a data connector scalar in terms of Open DD types
Key | Value | Required | Description |
---|---|---|---|
kind | DataConnectorScalarRepresentation | true | |
version | v1 | true | |
definition | DataConnectorScalarRepresentationV1 | true | The representation of a data connector scalar in terms of Open DD types. Deprecated in favour of BooleanExpressionType . |
DataConnectorScalarRepresentationV1
The representation of a data connector scalar in terms of Open DD types. Deprecated in favour of
BooleanExpressionType
.
Key | Value | Required | Description |
---|---|---|---|
dataConnectorName | DataConnectorName | true | The name of the data connector that this scalar type comes from. |
dataConnectorScalarType | DataConnectorScalarType | true | The name of the scalar type coming from the data connector. |
representation | TypeName | true | The name of the Open DD type that this data connector scalar type should be represented as. |
graphql | DataConnectorScalarGraphQLConfiguration / null | false | Configuration for how this scalar's operators should appear in the GraphQL schema. |
Example:
dataConnectorName: data_connector
dataConnectorScalarType: varchar
representation: String
graphql:
comparisonExpressionTypeName: String_Comparison_Exp
DataConnectorScalarGraphQLConfiguration
GraphQL configuration of a data connector scalar
Key | Value | Required | Description |
---|---|---|---|
comparisonExpressionTypeName | GraphQlTypeName / null | false |
GraphQlTypeName
The name of a GraphQL type.
Value: string
TypeName
The name of the Open DD type that this data connector scalar type should be represented as.
One of the following values:
Value | Description |
---|---|
InbuiltType | An inbuilt primitive OpenDD type. |
CustomTypeName |
CustomTypeName
The name of a user-defined type.
Value: string
InbuiltType
An inbuilt primitive OpenDD type.
Value: ID
/ Int
/ Float
/ Boolean
/ String
DataConnectorScalarType
The name of a scalar type in a data connector.
Value: string
DataConnectorName
The name of a data connector.
Value: string