KEkeboola
Buckets

Update a bucket

Updates the display name and the color of a bucket. With async=true the update is enqueued as a job (202). The synchronous variant is deprecated.

Initial response returns job details JobResponse. The result of the asynchronous job can be fetched via /v2/storage/jobs/{id}. When the job completes, final result is BucketUpdateJobResult.

Parameters of job will be BucketUpdateJobParams.

[Deprecated] This endpoint can be used synchronously as well. In that case, the final result is returned directly in the response BucketUpdateResponse.

put/v2/storage/buckets/{bucketId}

Request

Path parameters

bucketIdstring required

Identifier of the bucket to update.

Query parameters

asyncboolean

When true, the update is performed asynchronously as a job.

Request body

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.
colorstring nullable

New CSS color code of the bucket (e.g. #FF5733, red, rgb(255, 0, 0)). Pass null to remove the color.

Example request

{
  "displayName": "my-bucket"
}

Response

The updated bucket (synchronous, deprecated).

uristring required

API URI of the bucket.

idstring required

Bucket identifier ({stage}.{name}).

namestring required

Bucket name (prefixed with c-).

displayNamestring required

Human-readable display name shown in the UI.

idBranchinteger required

ID of the branch the bucket belongs to.

stage'in' | 'out' | 'sys' required

Bucket stage.

descriptionstring required

Bucket description.

tablesstring required

The same URI as uri, kept for backward compatibility.

createdstring required

Creation timestamp, ISO 8601 with a +hhmm offset; "" when none was recorded.

lastChangeDatestring nullable required

Timestamp of the last data change in the bucket, ISO 8601 with a +hhmm offset.

updatedstring nullable required

Timestamp of the last bucket update, ISO 8601 with a +hhmm offset.

isReadOnlyboolean required

Whether the bucket is read-only (linked or external buckets).

dataSizeBytesinteger required

Total data size in bytes.

rowsCountinteger required

Total number of rows.

isMaintenanceboolean required

Whether the bucket is in maintenance mode.

backendstring required

Storage backend of the bucket: snowflake, bigquery or postgres (external buckets); older buckets may carry another backend name.

sharing'organization' | 'organization-project' | 'specific-projects' | 'specific-users' | 'null' nullable required

Sharing type of the bucket; null when the bucket is not shared.

hasExternalSchemaboolean required

Whether the bucket is an external (registered) bucket.

databaseNamestring required

Database of a Snowflake external bucket or of a linked bucket's source; "" otherwise.

pathstring required

Dot-separated path of the bucket on the backend.

isSnowflakeSharedDatabaseboolean required

Whether the external bucket uses a Snowflake Secure Data Share.

isLinkedBucketboolean required

Whether this bucket is linked from another project.

colorstring nullable required

CSS color of the bucket.

bucketSharingAllowedboolean required

Whether the bucket can be shared.

backendPathstring[] required

Full path of the bucket on the backend (e.g. database and schema); [] on backends without one.

Example response

{
  "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-my-new-bucket",
  "id": "in.c-my-new-bucket",
  "name": "c-my-new-bucket",
  "displayName": "my-new-bucket",
  "idBranch": 1234,
  "stage": "in",
  "description": "Some Description",
  "tables": "https://connection.keboola.com/v2/storage/buckets/in.c-my-new-bucket",
  "created": "2017-02-13T12:01:05+0100",
  "updated": "2024-11-28T13:03:13+0100",
  "backend": "snowflake",
  "path": "database_name.c-my-new-bucket",
  "bucketSharingAllowed": true,
  "sharingParameters": {
    "projects": [
      {
        "id": 321,
        "name": "Some Project"
      }
    ],
    "users": [
      {
        "id": 5,
        "name": "Jan Developer",
        "email": "jan.dev@keboola.com"
      }
    ]
  },
  "sharedBy": {
    "id": 5,
    "name": "dev@keboola.com",
    "date": "2020-02-03T14:58:29+0100"
  },
  "owner": {
    "id": 123,
    "name": "Jan Developer",
    "email": "jan.dev@keboola.com"
  },
  "sourceBucket": {
    "id": "in.c-main",
    "name": "c-main",
    "displayName": "main",
    "stage": "in",
    "description": "Organization shared data",
    "sharing": "organization-project",
    "created": "2020-01-12T18:28:31+0100",
    "lastChangeDate": "2020-01-12T18:31:49+0100",
    "dataSizeBytes": 1536,
    "rowsCount": 32,
    "backend": "snowflake",
    "path": "database_name.c-main",
    "project": {
      "id": 123,
      "name": "Project name"
    },
    "tables": [
      {
        "id": "in.c-main.languages",
        "name": "languages",
        "displayName": "languages-display-name",
        "path": "/1234-languages"
      }
    ],
    "sharingParameters": {
      "projects": [
        {
          "id": 321,
          "name": "Some Project"
        }
      ],
      "users": [
        {
          "id": 5,
          "name": "Jan Developer",
          "email": "jan.dev@keboola.com"
        }
      ]
    },
    "sharedBy": {
      "id": 5,
      "name": "dev@keboola.com",
      "date": "2020-02-03T14:58:29+0100"
    },
    "owner": {
      "id": 123,
      "name": "Jan Developer",
      "email": "jan.dev@keboola.com"
    },
    "metadata": [
      {
        "id": "19509",
        "key": "some-key",
        "value": "Some value",
        "provider": "test-component",
        "timestamp": "2017-02-13T23:36:10+0100"
      }
    ]
  },
  "backendPath": [
    "KBC_PRJ_123",
    "in.c-my-new-bucket"
  ]
}

Changes

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