Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

CreateKxChangeset

Creates a changeset for a kdb database. A changeset allows you to add and delete existing files by using an ordered list of change requests.

Request Syntax


POST /kx/environments/environmentId/databases/databaseName/changesets HTTP/1.1
Content-type: application/json

{
   "changeRequests": [ 
      { 
         "changeType": "string",
         "dbPath": "string",
         "s3Path": "string"
      }
   ],
   "clientToken": "string"
}

URI Request Parameters

The request uses the following URI parameters.

databaseName

The name of the kdb database.

Length Constraints: Minimum length of 3. Maximum length of 63.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]*[a-zA-Z0-9]$

Required: Yes

environmentId

A unique identifier of the kdb environment.

Length Constraints: Minimum length of 1. Maximum length of 32.

Pattern: .*\S.*

Required: Yes

Request Body

The request accepts the following data in JSON format.

changeRequests

A list of change request objects that are run in order. A change request object consists of changeType , s3Path, and dbPath. A changeType can have the following values:

PUT – Adds or updates files in a database.
DELETE – Deletes files in a database.

All the change requests require a mandatory dbPath attribute that defines the path within the database directory. All database paths must start with a leading / and end with a trailing /. The s3Path attribute defines the s3 source file path and is required for a PUT change type. The s3path must end with a trailing / if it is a directory and must end without a trailing / if it is a file.

Here are few examples of how you can use the change request object:

This request adds a single sym file at database root location.

{ "changeType": "PUT", "s3Path":"s3://bucket/db/sym", "dbPath":"/"}
This request adds files in the given s3Path under the 2020.01.02 partition of the database.

{ "changeType": "PUT", "s3Path":"s3://bucket/db/2020.01.02/", "dbPath":"/2020.01.02/"}
This request adds files in the given s3Path under the taq table partition of the database.

[ { "changeType": "PUT", "s3Path":"s3://bucket/db/2020.01.02/taq/", "dbPath":"/2020.01.02/taq/"}]
This request deletes the 2020.01.02 partition of the database.

[{ "changeType": "DELETE", "dbPath": "/2020.01.02/"} ]
The DELETE request allows you to delete the existing files under the 2020.01.02 partition of the database, and the PUT request adds a new taq table under it.

[ {"changeType": "DELETE", "dbPath":"/2020.01.02/"}, {"changeType": "PUT", "s3Path":"s3://bucket/db/2020.01.02/taq/", "dbPath":"/2020.01.02/taq/"}]

Type: Array of ChangeRequest objects

Array Members: Minimum number of 1 item. Maximum number of 32 items.

Required: Yes

clientToken

A token that ensures idempotency. This token expires in 10 minutes.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Pattern: ^[a-zA-Z0-9-]+$

Required: Yes

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "changeRequests": [ 
      { 
         "changeType": "string",
         "dbPath": "string",
         "s3Path": "string"
      }
   ],
   "changesetId": "string",
   "createdTimestamp": number,
   "databaseName": "string",
   "environmentId": "string",
   "errorInfo": { 
      "errorMessage": "string",
      "errorType": "string"
   },
   "lastModifiedTimestamp": number,
   "status": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

changeRequests

A list of change requests.

Type: Array of ChangeRequest objects

Array Members: Minimum number of 1 item. Maximum number of 32 items.

changesetId

A unique identifier for the changeset.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 26.

Pattern: ^[a-zA-Z0-9]+$

createdTimestamp

The timestamp at which the changeset was created in FinSpace. The value is determined as epoch time in milliseconds. For example, the value for Monday, November 1, 2021 12:00:00 PM UTC is specified as 1635768000000.

Type: Timestamp

databaseName

The name of the kdb database.

Type: String

Length Constraints: Minimum length of 3. Maximum length of 63.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]*[a-zA-Z0-9]$

environmentId

A unique identifier for the kdb environment.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 32.

Pattern: .*\S.*

errorInfo

The details of the error that you receive when creating a changeset. It consists of the type of error and the error message.

Type: ErrorInfo object

lastModifiedTimestamp

The timestamp at which the changeset was updated in FinSpace. The value is determined as epoch time in milliseconds. For example, the value for Monday, November 1, 2021 12:00:00 PM UTC is specified as 1635768000000.

Type: Timestamp

status

Status of the changeset creation process.

Pending – Changeset creation is pending.
Processing – Changeset creation is running.
Failed – Changeset creation has failed.
Complete – Changeset creation has succeeded.

Type: String

Valid Values: PENDING | PROCESSING | FAILED | COMPLETED

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

You do not have sufficient access to perform this action.

HTTP Status Code: 403

ConflictException

There was a conflict with this action, and it could not be completed.

HTTP Status Code: 409

InternalServerException

The request processing has failed because of an unknown error, exception or failure.

HTTP Status Code: 500

LimitExceededException

A service limit or quota is exceeded.

HTTP Status Code: 400

ResourceNotFoundException

One or more resources can't be found.

HTTP Status Code: 404

ThrottlingException

The request was denied due to request throttling.

HTTP Status Code: 429

ValidationException

The input fails to satisfy the constraints specified by an AWS service.

HTTP Status Code: 400