KEkeboola
Buckets

Register bucket

EXPERIMENTAL

Use this API call to create a new bucket from an existing resource (schema or DB - depends on backend). Available for Snowflake and BigQuery backends only. Requires the external-buckets and input-mapping-read-only-storage project features and is available in the default branch only. The bucket is registered in a background job; to see the job detail use the Job Detail endpoint.

post/v2/storage/branch/{branchId}/buckets/register

Request

Path parameters

branchIdstring required

Request body

namestring required

The name of a bucket or a table.

  • Allowed characters: A-Z, a-z, 0-9, dash - and underscore _. Anything else — a space, a dot, an accented letter — is rejected, not transliterated.
  • 1 to 96 characters.
  • Cannot start with an underscore. A dash or a digit as the first character is fine.
  • Registered (external) buckets follow this same rule, dashes included.
  • Uniqueness is case-insensitive within a stage: creating MyBucket next to mybucket fails with storage.buckets.alreadyExists, and for tables with storage.buckets.tableAlreadyExists or storage.validation.tableAlreadyExists.
  • To turn arbitrary user input into a name that satisfies this rule, call POST /v2/storage/webalize/display-name instead of reimplementing the transformation. It unaccents the input, replaces every run of disallowed characters with a single -, trims - from both ends, strips leading underscores, and truncates to 96 characters.
displayNamestring

The name of a bucket or a table.

  • Allowed characters: A-Z, a-z, 0-9, dash - and underscore _. Anything else — a space, a dot, an accented letter — is rejected, not transliterated.
  • 1 to 96 characters.
  • Cannot start with an underscore. A dash or a digit as the first character is fine.
  • Registered (external) buckets follow this same rule, dashes included.
  • Uniqueness is case-insensitive within a stage: creating MyBucket next to mybucket fails with storage.buckets.alreadyExists, and for tables with storage.buckets.tableAlreadyExists or storage.validation.tableAlreadyExists.
  • To turn arbitrary user input into a name that satisfies this rule, call POST /v2/storage/webalize/display-name instead of reimplementing the transformation. It unaccents the input, replaces every run of disallowed characters with a single -, trims - from both ends, strips leading underscores, and truncates to 96 characters.
stage'in' | 'out' | 'sys'

Assigns the bucket to one of the stages.

backend'bigquery' | 'snowflake' nullable

Bucket backend type; the default value is determined by the project settings.

descriptionstring nullable

Bucket description.

pathstring[] required

Path to the schema. Snowflake: ["database-name", "schema-name"]; BigQuery: ["projectId", "location", "exchangerName", "listingName"].

isSnowflakeSharedDatabaseboolean

Whether the external bucket uses the Snowflake Secure Data Share feature. Valid for the Snowflake backend only.

Example request

{
  "name": "my-bucket",
  "displayName": "my-bucket",
  "stage": "in",
  "backend": "snowflake",
  "description": "my bucket",
  "path": [
    "DATABASE",
    "SCHEMA"
  ]
}

Response

Bucket registration job enqueued; returns job details.

idstring required

Job ID.

statusstring required

Current status of the job.

urlstring required

API detail URL for the job.

tableIdstring nullable required

ID of the table affected by the job.

operationNamestring required

Type of operation performed.

operationParamsobject required

Parameters for the operation.

createdTimestring date-time required

Job creation timestamp.

startTimestring date-time nullable required

Job start timestamp.

endTimestring date-time nullable required

Job end timestamp.

runIdstring nullable required

Run ID for the job.

Example response

{
  "id": "22077337",
  "status": "waiting",
  "url": "https://connection.keboola.com/v2/storage/jobs/22077337",
  "tableId": null,
  "operationName": "workspaceLoad",
  "operationParams": {
    "workspaceId": "78423",
    "preserve": false,
    "input": [
      {
        "source": "in.c-application-testing.cashier-data",
        "destination": "my-table"
      }
    ],
    "queue": "main_fast"
  },
  "createdTime": "2017-02-13T16:41:18+0100",
  "startTime": null,
  "endTime": null,
  "runId": null,
  "results": null,
  "creatorToken": {
    "id": "27978",
    "description": "john.doe@keboola.com"
  },
  "actor": {
    "type": "token",
    "id": "27978",
    "name": "john.doe@keboola.com",
    "adminId": 1234
  },
  "metrics": {
    "inCompressed": false,
    "inBytes": 0,
    "inBytesUncompressed": 0,
    "outCompressed": false,
    "outBytes": 0,
    "outBytesUncompressed": 0
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.