Data Connectors

Introduction

A DataConnectorLink is a way to specify where your data comes from and how it can be used. It can connect to various types of data sources, like SQL databases, NoSQL databases, REST APIs, GraphQL APIs, files, and more.

The DataConnectorLink uses the ConnectorManifest it's associated with to introspect the respective data source and generate a schema that can be used to query and mutate the data.

Generate DataConnectorLink using the CLI

When you run the add connector-manifest command, the CLI generates a DataConnectorLink for you. Upon the connector's first build, the schema is introspected and the DataConnectorLink is updated with the schema according to the data source.

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.

DataConnectorLinkV1

Definition of a data connector - version 1.

Key	Value	Required	Description
name	DataConnectorName	true	The name of the data connector.
url	DataConnectorUrlRef	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.
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.

Example:

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.0
    capabilities:
      query:
        variables: {}
      mutation: {}

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

DataConnectorUrlRef

The url(s) to access the data connector.

One of the following values:

Value	Description
DataConnectorUrlV1
Fn::ManifestRef	Refer a ConnectorManifest to build and derive the connector URL from

Fn::ManifestRef

Refer a ConnectorManifest to build and derive the connector URL from

Key	Value	Required	Description
Fn::ManifestRef	string	true

DataConnectorUrlV1

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