Search documentation
karat

+

K

User Documentation ↗
Version 2.0

Create File Import

POST/api/v2/connectivity/connections/{connectionRid}/fileImports
Warning

This endpoint is in preview and may be modified or removed at any time. To use this endpoint, add preview=true to the request query parameters.

Creates a new FileImport.

Third-party applications using this endpoint via OAuth2 must request the following operation scope: api:connectivity-file-import-write.

Path parameters

connectionRid
string

The Resource Identifier (RID) of a Connection (also known as a source).

Query parameters

preview
boolean
optional

Enables the use of preview functionality.

Request body

CreateFileImportRequest
object
Hide child attributes

Hide child attributes

datasetRid
string

The RID of the output dataset.

importMode
string (enum)

Import mode governs how raw files are read from an external system, and written into a Foundry dataset.

SNAPSHOT: Defines a new dataset state consisting only of files from a particular import execution. APPEND: Purely additive and yields data from previous import executions in addition to newly added files. UPDATE: Replaces existing files from previous import executions based on file names.

Enum values: SNAPSHOT, APPEND, UPDATE

displayName
string
branchName
string
optional

The branch name in the output dataset that will contain the imported data. Defaults to master for most enrollments.

subfolder
string
optional

A subfolder in the external system that will be imported. If not specified, defaults to the root folder of the external system.

fileImportFilters
list<FileImportFilter>
optional

Use filters to limit which files should be imported. Filters are applied in the order they are defined. A different ordering of filters may lead to a more optimized import. Learn more about optimizing file imports.

Show child attributes

Show child attributes

Response body

FileImport
object

The created FileImport

Hide child attributes

Hide child attributes

rid
string

The Resource Identifier (RID) of a FileImport (also known as a batch sync).

connectionRid
string

The RID of the Connection (also known as a source) that the File Import uses to import data.

datasetRid
string

The RID of the output dataset.

branchName
string
optional

The branch name in the output dataset that will contain the imported data. Defaults to master for most enrollments.

displayName
string
fileImportFilters
list<FileImportFilter>
optional

Use filters to limit which files should be imported. Filters are applied in the order they are defined. A different ordering of filters may lead to a more optimized import. Learn more about optimizing file imports.

Show child attributes

Show child attributes

importMode
string (enum)

Import mode governs how raw files are read from an external system, and written into a Foundry dataset.

SNAPSHOT: Defines a new dataset state consisting only of files from a particular import execution. APPEND: Purely additive and yields data from previous import executions in addition to newly added files. UPDATE: Replaces existing files from previous import executions based on file names.

Enum values: SNAPSHOT, APPEND, UPDATE

subfolder
string
optional

A subfolder in the external system that will be imported. If not specified, defaults to the root folder of the external system.

Examples

Request

Copied!
1 2 3 4 5 curl -X POST \ -H "Content-type: application/json" \ -H "Authorization: Bearer $TOKEN" \ "https://$HOSTNAME/api/v2/connectivity/connections/ri.magritte..source.c078b71b-92f9-41b6-b0df-3760f411120b/fileImports?preview=true" \ -d '{"datasetRid":"ri.foundry.main.dataset.c26f11c8-cdb3-4f44-9f5d-9816ea1c82da","importMode":"SNAPSHOT","displayName":"My file import","branchName":"master","subfolder":"subfolder1/subfolder2"}'

Response

Copied!
1 2 3 4 5 6 7 8 9 { "datasetRid": "ri.foundry.main.dataset.c26f11c8-cdb3-4f44-9f5d-9816ea1c82da", "importMode": "SNAPSHOT", "displayName": "My file import", "connectionRid": "ri.magritte..source.c078b71b-92f9-41b6-b0df-3760f411120b", "branchName": "master", "subfolder": "subfolder1/subfolder2", "rid": "ri.magritte..extract.27bb4f2b-63b8-44b8-a579-4e2bd65ba158" }

Error responses

Error Name
ConnectionDetailsNotDeterminedError CodeINTERNAL
Status Code500
DescriptionDetails of the connection (such as which types of import it supports) could not be determined.
ParametersconnectionRid, connectionType
FileSizeFilterMissingGreaterThanAndLessThanError CodeINVALID_ARGUMENT
Status Code400
DescriptionBoth the `gt` and `lt` properties are missing from the FileSizeFilter. At least one of these properties must be present
FileSizeFilterGreaterThanCannotBeNegativeError CodeINVALID_ARGUMENT
Status Code400
DescriptionThe `gt` property in the FileSizeFilter cannot be a negative number.
Parametersgt
FileSizeFilterLessThanMustBeOneByteOrLargerError CodeINVALID_ARGUMENT
Status Code400
DescriptionThe `lt` property in the FileSizeFilter must be at least 1 byte.
Parameterslt
FileSizeFilterInvalidGreaterThanAndLessThanRangeError CodeINVALID_ARGUMENT
Status Code400
DescriptionThe provided `gt` and `lt` properties in the FileSizeFilter are invalid. No files will ever satisfy the provided range. The value specified for `gt` must be strictly less than `lt - 1`.
Parametersgt, lt
FileAtLeastCountFilterInvalidMinCountError CodeINVALID_ARGUMENT
Status Code400
DescriptionThe provided `minFilesCount` property in the FileAtLeastCountFilter must be strictly greater than 0.
ParametersminFilesCount
FileImportCustomFilterCannotBeUsedToCreateOrUpdateFileImportsError CodeINVALID_ARGUMENT
Status Code400
DescriptionCustom file import filters can be fetched but cannot currently be used when creating or updating file imports.
Parametersconfig
FileImportNotSupportedForConnectionError CodeINVALID_ARGUMENT
Status Code400
DescriptionThe specified connection does not support file imports.
ParametersconnectionRid
CreateFileImportPermissionDeniedError CodePERMISSION_DENIED
Status Code403
DescriptionCould not create the FileImport.
ParametersconnectionRid