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 OpenDD 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.

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	[ArgumentPreset]	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	string	true	Name of the field in the NDC function/procedure's result which contains the response headers
resultField	string	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 conector to be set as response headers

ArgumentPreset

An argument preset that can be applied to all functions/procedures of a connector

Key	Value	Required	Description
argument	ArgumentName	true
value	ArgumentPresetValue	true

ArgumentPresetValue

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	Used to represent the name of a session variable, like "x-hasura-role".
booleanExpression	ModelPredicate	false

ModelPredicate

A predicate that can be used to restrict the objects returned when querying a model.

Must have exactly one of the following fields:

Key	Value	Required	Description
fieldComparison	FieldComparisonPredicate	false	Field comparison predicate filters objects based on a field value.
fieldIsNull	FieldIsNullPredicate	false	Predicate to check if the given field is null.
relationship	RelationshipPredicate	false	Relationship predicate filters objects of a source model based on a predicate on the related model.
and	[ModelPredicate]	false
or	[ModelPredicate]	false
not	ModelPredicate	false

Example:

fieldComparison:
  field: author_id
  operator: _eq
  value:
    sessionVariable: x-hasura-user-id

RelationshipPredicate

Relationship predicate filters objects of a source model based on a predicate on the related model.

Key	Value	Required	Description
name	RelationshipName	true	The name of the relationship of the object type of the model to follow.
predicate	ModelPredicate / null	false	The predicate to apply on the related objects. If this is null, then the predicate evaluates to true as long as there is at least one related object present.

RelationshipName

The name of the GraphQL relationship field.

Value: string

FieldIsNullPredicate

Predicate to check if the given field is null.

Key	Value	Required	Description
field	FieldName	true	The name of the field that should be checked for a null value.

FieldComparisonPredicate

Field comparison predicate filters objects based on a field value.

Key	Value	Required	Description
field	FieldName	true	The field name of the object type of the model to compare.
operator	string	true	The name of the operator to use for comparison.
value	ValueExpression	true	The value expression to compare against.

FieldName

The name of a field in a user-defined object type.

Value: string

ArgumentName

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

DataConnectorScalarRepresentationV1

The representation of a data connector scalar in terms of Open DD types

Key	Value	Required	Description
dataConnectorName	DataConnectorName	true	The name of the data connector that this scalar type comes from.
dataConnectorScalarType	string	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

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

DataConnectorName

The name of a data connector.

Value: string