Data Connector Links

Introduction

A DataConnectorLink is 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.

Be more granular

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:

• Add models
• Add commands
• Add relationships

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

A sample DataConnectorLink:

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	DataConnectorArgumentName	true	The name of an argument as defined by a data connector.
value	DataConnectorArgumentPresetValue	true	The value of a data connector argument preset.

DataConnectorArgumentPresetValue

The value of a data connector argument preset.

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

Key value map of HTTP headers to be forwarded in the headers argument of a data connector request.

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

DataConnectorArgumentName

The name of an argument as defined by a data connector.

Value: string

SchemaAndCapabilitiesV01

Version 0.1 of schema and capabilities for a data connector.

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

DataConnectorUrlV1

A URL to access a data connector. This can be a single URL or a pair of read and write URLs.

Must have exactly one of the following fields:

Key	Value	Required	Description
singleUrl	EnvironmentValue	false
readWriteUrls	ReadWriteUrls	false	A pair of URLs to access a data connector, one for reading and one for writing.

ReadWriteUrls

A pair of URLs to access a data connector, one for reading and one for writing.

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