Create connection

posthttps://api.faraday.ai/v1/connections

Add a new connection.

Connections are configuration for connecting data between Faraday and an external location. They are required when working with replication targets.

All connections have a type that determines which options may be specified.

Connection type is specified in the options object.

Authentication

Bearer Authentication

Provide your API key in the Authorization header. You can find your API key in the Settings page of the dashboard.

Authorization: Bearer YOUR_TOKEN

Body

The definition of the new connection

namestringrequired

A user-friendly name of the connection.

Example: "Snowflake AWS - Marketing"
Match pattern: ^(?!\s*$).+
Maximum characters: 64
optionsdiscriminated type (type)required

The connection-specific options. These vary by connection type.

Properties of discriminated type (type)
type
type#stringrequireddiscriminator
Value: "athena"
aws_account_idstringrequired

Twelve-digit AWS account ID that owns the Glue catalog Faraday should query.

Match pattern: ^[0-9]{12}$
aws_customer_role_arnstring

IAM role in your AWS account that Faraday assumes to run Athena. Create the Faraday connection first, trust aws_iam_role_arn on this role, then set this field.

Match pattern: ^arn:aws:iam::[0-9]+:role/.+$
aws_regionstringrequired

Region of the Glue catalog and the S3 output location, e.g. us-east-1.

Match pattern: ^[a-z0-9\-]+$
databasestringrequired

Glue/Athena database Faraday should read from and write to.

Match pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
s3_output_locationstringrequired

s3://bucket/prefix/ where Faraday stages extracts, query results, and target tables. Grant the role in aws_customer_role_arn read and write on this prefix.

Match pattern: ^s3://[a-z0-9.\-]+(/.*)?$
workgroupstring

Athena workgroup in your AWS account. Defaults to primary.

Match pattern: ^[a-zA-Z0-9._-]{1,128}$

Responses

201The new connection
archived_atstring<date-time>

If not null, this resource will no longer receive updates, but will still be visable.

contentsarray[object]
Example: ["my_table_1","my_table_2"]
Items of array[object]
namestringrequired

The name of a table or object found in the connection

Example: "my_table_1"
object_sizeinteger

Object size in bytes. Only applicable to object stores (S3, GCS, etc).

row_countinteger

Row count if available from this connection type. Only applicable to databases and data warehouses. Some do not have an efficient row count mechanism (e.g. Postgres) and so this is not provided.

contents_errorstring

The error encountered when trying to connect, if any

Example: "Password incorrect"
created_atstring<date-time>required

When this resource was created.

directionalitystringrequired

Whether the connection can be used as a source (for datasets), a destination (for targets), or both.

Allowed values: bidirectional, source_only, destination_only
idstring<uuid>required

A unique ID for this resource.

Example: "5e0dfa56-2d52-4c06-a870-bc79c71e86a3"
last_read_input_atstring<date-time>

The last time this resource's input was read.

last_updated_config_atstring<date-time>

The last time this resource's configuration was updated. If this is more recent than last_updated_output_at, the resource will be rebuilt.

last_updated_output_atstring<date-time>

The last time this resource successfully built.

managedboolean

A managed connection requires special configuration from a Faraday admin, and is read-only.

Example: true
namestringrequired

A user-friendly name of the connection.

Example: "Snowflake AWS - Marketing"
Match pattern: ^(?!\s*$).+
Maximum characters: 64
optionsdiscriminated type (type)required

The connection-specific options. These vary by connection type.

Properties of discriminated type (type)
type
type#stringrequireddiscriminator
Value: "athena"
aws_account_idstringrequired

Twelve-digit AWS account ID that owns the Glue catalog Faraday should query.

Match pattern: ^[0-9]{12}$
aws_customer_role_arnstring

IAM role in your AWS account that Faraday assumes to run Athena. Create the Faraday connection first, trust aws_iam_role_arn on this role, then set this field.

Match pattern: ^arn:aws:iam::[0-9]+:role/.+$
aws_iam_role_arnstring

AWS IAM role Faraday generated for this connection. Create a role in your AWS account that trusts this ARN, grant that role Athena, Glue, and S3, set aws_customer_role_arn, then force-update. Unique per Faraday Athena connection.

Match pattern: ^arn:aws:iam::[0-9]+:role/.+$
aws_regionstringrequired

Region of the Glue catalog and the S3 output location, e.g. us-east-1.

Match pattern: ^[a-z0-9\-]+$
databasestringrequired

Glue/Athena database Faraday should read from and write to.

Match pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
s3_output_locationstringrequired

s3://bucket/prefix/ where Faraday stages extracts, query results, and target tables. Grant the role in aws_customer_role_arn read and write on this prefix.

Match pattern: ^s3://[a-z0-9.\-]+(/.*)?$
workgroupstring

Athena workgroup in your AWS account. Defaults to primary.

Match pattern: ^[a-zA-Z0-9._-]{1,128}$
resource_typestringrequired

The type of this resource.

Example: "connections"
statusstringrequired

The current state of this resource and any updates.

Example: "pending"
Allowed values: new, starting, running, ready, error
status_changed_atstring<date-time>

When the status of this resource was last updated.

status_errorstring

If this resource has status == "error", this will contain an error message.

updated_atstring<date-time>required

When this resource was last updated.

400The request was invalid.
errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

  • BAD_REQUEST: The request could not be validated.
  • FORBIDDEN: You do not have permission to access the specified resour...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

401No API key was supplied.
errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

  • BAD_REQUEST: The request could not be validated.
  • FORBIDDEN: You do not have permission to access the specified resour...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

403Access to this resource was forbidden.
errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

  • BAD_REQUEST: The request could not be validated.
  • FORBIDDEN: You do not have permission to access the specified resour...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

404The requested resource ID was not found.
errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

  • BAD_REQUEST: The request could not be validated.
  • FORBIDDEN: You do not have permission to access the specified resour...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

500An internal server error occurred.
errorstringrequired

A Faraday error code.

Some possible values include:

Generic HTTP Errors

  • BAD_REQUEST: The request could not be validated.
  • FORBIDDEN: You do not have permission to access the specified resour...
Example: "ERROR_TYPE"
Allowed values: BAD_REQUEST, FORBIDDEN, MAX_RESOURCES_REACHED, INTERNAL_SERVER_ERROR, INVALID_AUTHORIZATION, NOT_FOUND, MALFORMED_API_KEY, MISSING_API_KEY, EXPIRED_API_KEY, VALIDATION_FAILED, CONFLICT
idstring<uuid>required

A unique ID for this error. Please include this in bug reports.

Example: "082f9513-901c-4308-8081-902a8fe22d7e"
notestringrequired

A human-readable description of the error.

Example: "An error occurred"
validationErrorsarray[object]

JSON Schema validation errors, if any.

Items of array[object]
contextobjectrequired

More information about the error.

Properties of object
errorTypestringrequired

The type of validation error which occurred.

messagestringrequired

A human-readable error message.

pathstringrequired

The location in the document that failed validation.

suggestionstring

A suggestion for fixing this error.

Tags

connections