Skip to content

Latest commit

 

History

History
652 lines (495 loc) · 18.6 KB

housetables.md

File metadata and controls

652 lines (495 loc) · 18.6 KB
Raw

House Tables API v0.0.1

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

API description for House Tables API

Base URLs:

Terms of service

License: Apache 2.0

UserTable

Get User Table identified by databaseID and tableId.

Code samples

GET /hts/tables

Returns a User House Table identified by databaseID and tableId.

Parameters

Name In Type Required Description
databaseId query string true none
tableId query string true none

Example responses

200 Response

{
  "entity": {
    "tableId": "my_table",
    "databaseId": "my_database",
    "tableVersion": "string",
    "metadataLocation": "string"
  }
}

Responses

Status Meaning Description Schema
200 OK User Table GET: OK EntityResponseBodyUserTable
404 Not Found User Table GET: TBL_DB_NOT_FOUND EntityResponseBodyUserTable
This operation does not require authentication

Update a User Table

Code samples

PUT /hts/tables

Updates or creates a User House Table identified by databaseID and tableId. If the table does not exist, it will be created. If the table exists, it will be updated.

Body parameter

{
  "entity": {
    "tableId": "my_table",
    "databaseId": "my_database",
    "tableVersion": "string",
    "metadataLocation": "string"
  }
}

Parameters

Name In Type Required Description
body body CreateUpdateEntityRequestBodyUserTable true none

Example responses

200 Response

{
  "entity": {
    "tableId": "my_table",
    "databaseId": "my_database",
    "tableVersion": "string",
    "metadataLocation": "string"
  }
}

Responses

Status Meaning Description Schema
200 OK User Table PUT: UPDATED EntityResponseBodyUserTable
201 Created User Table PUT: CREATED EntityResponseBodyUserTable
400 Bad Request User Table PUT: BAD_REQUEST EntityResponseBodyUserTable
404 Not Found User Table PUT: DB_NOT_FOUND EntityResponseBodyUserTable
409 Conflict User Table PUT: CONFLICT EntityResponseBodyUserTable
This operation does not require authentication

Delete a User Table

Code samples

DELETE /hts/tables

Delete a User House Table entry identified by databaseID and tableId.

Parameters

Name In Type Required Description
databaseId query string true none
tableId query string true none

Responses

Status Meaning Description Schema
204 No Content User Table DELETE: NO_CONTENT None
400 Bad Request User Table DELETE: BAD_REQUEST None
404 Not Found User Table DELETE: TBL_DB_NOT_FOUND None
This operation does not require authentication

Search User Table by filter.

Code samples

GET /hts/tables/query

Returns user table from house table that fulfills the predicate. For examples, one could provide {databaseId: d1} in the map to query all tables from database d1.

Parameters

Name In Type Required Description
parameters query object true none

Example responses

200 Response

{
  "results": [
    {
      "tableId": "my_table",
      "databaseId": "my_database",
      "tableVersion": "string",
      "metadataLocation": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK User Table GET: OK GetAllEntityResponseBodyUserTable
This operation does not require authentication

Job

Get job details for a given jobId.

Code samples

GET /hts/jobs

Returns a Job entity identified by jobId

Parameters

Name In Type Required Description
jobId query string true none

Example responses

200 Response

{
  "entity": {
    "jobId": "24efc962-9962-4522-b0b6-29490d7d8a0e",
    "state": "QUEUED",
    "version": "539482",
    "jobName": "my_job",
    "clusterId": "my_cluster",
    "creationTimeMs": 1651002318265,
    "startTimeMs": 1651002318265,
    "finishTimeMs": 1651002318265,
    "lastUpdateTimeMs": 1651002318265,
    "jobConf": "{'jobType': 'RETENTION', 'table': 'db.tb'}",
    "heartbeatTimeMs": 1651002318265,
    "executionId": "application_1642969576960_13278206"
  }
}

Responses

Status Meaning Description Schema
200 OK Job GET: OK EntityResponseBodyJob
404 Not Found Job GET: NOT_FOUND EntityResponseBodyJob
This operation does not require authentication

Update a Job

Code samples

PUT /hts/jobs

Updates or creates a Job in the House Table and returns the job resources. If the job does not exist, it will be created. If the job exists, it will be updated.

Body parameter

{
  "entity": {
    "jobId": "24efc962-9962-4522-b0b6-29490d7d8a0e",
    "state": "QUEUED",
    "version": "539482",
    "jobName": "my_job",
    "clusterId": "my_cluster",
    "creationTimeMs": 1651002318265,
    "startTimeMs": 1651002318265,
    "finishTimeMs": 1651002318265,
    "lastUpdateTimeMs": 1651002318265,
    "jobConf": "{'jobType': 'RETENTION', 'table': 'db.tb'}",
    "heartbeatTimeMs": 1651002318265,
    "executionId": "application_1642969576960_13278206"
  }
}

Parameters

Name In Type Required Description
body body CreateUpdateEntityRequestBodyJob true none

Example responses

200 Response

{
  "entity": {
    "jobId": "24efc962-9962-4522-b0b6-29490d7d8a0e",
    "state": "QUEUED",
    "version": "539482",
    "jobName": "my_job",
    "clusterId": "my_cluster",
    "creationTimeMs": 1651002318265,
    "startTimeMs": 1651002318265,
    "finishTimeMs": 1651002318265,
    "lastUpdateTimeMs": 1651002318265,
    "jobConf": "{'jobType': 'RETENTION', 'table': 'db.tb'}",
    "heartbeatTimeMs": 1651002318265,
    "executionId": "application_1642969576960_13278206"
  }
}

Responses

Status Meaning Description Schema
200 OK Job PUT: UPDATED EntityResponseBodyJob
201 Created Job PUT: CREATED EntityResponseBodyJob
400 Bad Request Job PUT: BAD_REQUEST EntityResponseBodyJob
404 Not Found Job PUT: DB_NOT_FOUND EntityResponseBodyJob
409 Conflict Job PUT: CONFLICT EntityResponseBodyJob
This operation does not require authentication

Delete a Job

Code samples

DELETE /hts/jobs

Delete a Job entity identified by jobId

Parameters

Name In Type Required Description
jobId query string true none

Responses

Status Meaning Description Schema
204 No Content Job DELETE: NO_CONTENT None
400 Bad Request Job DELETE: BAD_REQUEST None
404 Not Found Job DELETE: NOT_FOUND None
This operation does not require authentication

Search Jobs by filter

Code samples

GET /hts/jobs/query

Returns jobs that fulfills the filter predicate. For examples, one could provide {status: } in the map to query all jobs with that status.

Parameters

Name In Type Required Description
parameters query object true none

Example responses

200 Response

{
  "results": [
    {
      "jobId": "24efc962-9962-4522-b0b6-29490d7d8a0e",
      "state": "QUEUED",
      "version": "539482",
      "jobName": "my_job",
      "clusterId": "my_cluster",
      "creationTimeMs": 1651002318265,
      "startTimeMs": 1651002318265,
      "finishTimeMs": 1651002318265,
      "lastUpdateTimeMs": 1651002318265,
      "jobConf": "{'jobType': 'RETENTION', 'table': 'db.tb'}",
      "heartbeatTimeMs": 1651002318265,
      "executionId": "application_1642969576960_13278206"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Job GET: OK GetAllEntityResponseBodyJob
This operation does not require authentication

Schemas

CreateUpdateEntityRequestBodyUserTable

{
  "entity": {
    "tableId": "my_table",
    "databaseId": "my_database",
    "tableVersion": "string",
    "metadataLocation": "string"
  }
}

Request containing details of the User Table to be created/updated

Properties

Name Type Required Restrictions Description
entity UserTable true none The entity object that clients want to create/update in the target house table.

UserTable

{
  "tableId": "my_table",
  "databaseId": "my_database",
  "tableVersion": "string",
  "metadataLocation": "string"
}

The entity object that clients want to create/update in the target house table.

Properties

Name Type Required Restrictions Description
tableId string true none Unique Resource identifier for a table within a Database.
databaseId string true none Unique Resource identifier for the Database containing the Table. Together with tableID they form a composite primary key for a user table.
tableVersion string false none Current Version of the user table.
metadataLocation string true none Full URI for the file manifesting the newest version of a user table.

EntityResponseBodyUserTable

{
  "entity": {
    "tableId": "my_table",
    "databaseId": "my_database",
    "tableVersion": "string",
    "metadataLocation": "string"
  }
}

Properties

Name Type Required Restrictions Description
entity UserTable true none The entity object that clients want to create/update in the target house table.

CreateUpdateEntityRequestBodyJob

{
  "entity": {
    "jobId": "24efc962-9962-4522-b0b6-29490d7d8a0e",
    "state": "QUEUED",
    "version": "539482",
    "jobName": "my_job",
    "clusterId": "my_cluster",
    "creationTimeMs": 1651002318265,
    "startTimeMs": 1651002318265,
    "finishTimeMs": 1651002318265,
    "lastUpdateTimeMs": 1651002318265,
    "jobConf": "{'jobType': 'RETENTION', 'table': 'db.tb'}",
    "heartbeatTimeMs": 1651002318265,
    "executionId": "application_1642969576960_13278206"
  }
}

Request containing details of the User Table to be created/updated

Properties

Name Type Required Restrictions Description
entity Job true none The entity object that clients want to create/update in the target house table.

Job

{
  "jobId": "24efc962-9962-4522-b0b6-29490d7d8a0e",
  "state": "QUEUED",
  "version": "539482",
  "jobName": "my_job",
  "clusterId": "my_cluster",
  "creationTimeMs": 1651002318265,
  "startTimeMs": 1651002318265,
  "finishTimeMs": 1651002318265,
  "lastUpdateTimeMs": 1651002318265,
  "jobConf": "{'jobType': 'RETENTION', 'table': 'db.tb'}",
  "heartbeatTimeMs": 1651002318265,
  "executionId": "application_1642969576960_13278206"
}

The entity object that clients want to create/update in the target house table.

Properties

Name Type Required Restrictions Description
jobId string true none Unique Resource identifier for a job within a Database.
state string false none State for the job
version string false none Version of the job entry in HTS. HTS internally generates the next version after a successful PUT.The value would be a string representing a random integer.
jobName string true none Name of a job, doesn't need to be unique
clusterId string true none Unique identifier for the cluster
creationTimeMs integer(int64) false none Job creation time in unix epoch milliseconds
startTimeMs integer(int64) false none Job start time in unix epoch milliseconds
finishTimeMs integer(int64) false none Job finish time in unix epoch milliseconds
lastUpdateTimeMs integer(int64) false none Job contents last update time in unix epoch milliseconds
jobConf string false none Job config
heartbeatTimeMs integer(int64) false none Running job heartbeat timestamp in milliseconds
executionId string false none Launched job execution id specific to engine

EntityResponseBodyJob

{
  "entity": {
    "jobId": "24efc962-9962-4522-b0b6-29490d7d8a0e",
    "state": "QUEUED",
    "version": "539482",
    "jobName": "my_job",
    "clusterId": "my_cluster",
    "creationTimeMs": 1651002318265,
    "startTimeMs": 1651002318265,
    "finishTimeMs": 1651002318265,
    "lastUpdateTimeMs": 1651002318265,
    "jobConf": "{'jobType': 'RETENTION', 'table': 'db.tb'}",
    "heartbeatTimeMs": 1651002318265,
    "executionId": "application_1642969576960_13278206"
  }
}

Properties

Name Type Required Restrictions Description
entity Job true none The entity object that clients want to create/update in the target house table.

GetAllEntityResponseBodyUserTable

{
  "results": [
    {
      "tableId": "my_table",
      "databaseId": "my_database",
      "tableVersion": "string",
      "metadataLocation": "string"
    }
  ]
}

Properties

Name Type Required Restrictions Description
results [UserTable] false read-only List of user table objects in House table

GetAllEntityResponseBodyJob

{
  "results": [
    {
      "jobId": "24efc962-9962-4522-b0b6-29490d7d8a0e",
      "state": "QUEUED",
      "version": "539482",
      "jobName": "my_job",
      "clusterId": "my_cluster",
      "creationTimeMs": 1651002318265,
      "startTimeMs": 1651002318265,
      "finishTimeMs": 1651002318265,
      "lastUpdateTimeMs": 1651002318265,
      "jobConf": "{'jobType': 'RETENTION', 'table': 'db.tb'}",
      "heartbeatTimeMs": 1651002318265,
      "executionId": "application_1642969576960_13278206"
    }
  ]
}

Properties

Name Type Required Restrictions Description
results [Job] false read-only List of user table objects in House table