Databases and Tables

Describe All

Returns the definitions of all databases and tables within the database. Record counts about 5000 records are estimated, as determining the exact count can be expensive. When the record count is estimated, this is indicated by the inclusion of a confidence interval of estimated_record_range. If you need the exact count, you can include an "exact_count": true in the operation, but be aware that this requires a full table scan (may be expensive).

operation (required) - must always be describe_all

Body

{
    "operation": "describe_all"
}

Response: 200

{
    "dev": {
        "dog": {
          "schema": "dev",
          "name": "dog",
          "hash_attribute": "id",
          "audit": true,
          "schema_defined": false,
          "attributes": [
            {
              "attribute": "id",
              "indexed": true,
              "is_primary_key": true
            },
            {
              "attribute": "__createdtime__",
              "indexed": true
            },
            {
              "attribute": "__updatedtime__",
              "indexed": true
            },
            {
              "attribute": "type",
              "indexed": true
            }
          ],
          "clustering_stream_name": "dd9e90c2689151ab812e0f2d98816bff",
          "record_count": 4000,
          "estimated_record_range": [3976, 4033],
          "last_updated_record": 1697658683698.4504
        }
    }
}

Describe database

Returns the definitions of all tables within the specified database.

operation (required) - must always be describe_database
database (optional) - database where the table you wish to describe lives. The default is data

Body

{
    "operation": "describe_database",
    "database": "dev"
}

Response: 200

{
    "dog": {
      "schema": "dev",
      "name": "dog",
      "hash_attribute": "id",
      "audit": true,
      "schema_defined": false,
      "attributes": [
        {
          "attribute": "id",
          "indexed": true,
          "is_primary_key": true
        },
        {
          "attribute": "__createdtime__",
          "indexed": true
        },
        {
          "attribute": "__updatedtime__",
          "indexed": true
        },
        {
          "attribute": "type",
          "indexed": true
        }
      ],
      "clustering_stream_name": "dd9e90c2689151ab812e0f2d98816bff",
      "record_count": 4000,
      "estimated_record_range": [3976, 4033],
      "last_updated_record": 1697658683698.4504
    }
}

Describe Table

Returns the definition of the specified table.

operation (required) - must always be describe_table
table (required) - table you wish to describe
database (optional) - database where the table you wish to describe lives. The default is data

Body

{
    "operation": "describe_table",
    "table": "dog"
}

Response: 200

{
  "schema": "dev",
  "name": "dog",
  "hash_attribute": "id",
  "audit": true,
  "schema_defined": false,
  "attributes": [
    {
      "attribute": "id",
      "indexed": true,
      "is_primary_key": true
    },
    {
      "attribute": "__createdtime__",
      "indexed": true
    },
    {
      "attribute": "__updatedtime__",
      "indexed": true
    },
    {
      "attribute": "type",
      "indexed": true
    }
  ],
  "clustering_stream_name": "dd9e90c2689151ab812e0f2d98816bff",
  "record_count": 4000,
  "estimated_record_range": [3976, 4033],
  "last_updated_record": 1697658683698.4504
}

Create database

Create a new database.

Operation is restricted to super_user roles only

operation (required) - must always be create_database
database (optional) - name of the database you are creating. The default is data

Body

{
    "operation": "create_database",
    "database": "dev"
}

Response: 200

{
    "message": "database 'dev' successfully created"
}

Drop database

Drop an existing database. NOTE: Dropping a database will delete all tables and all of their records in that database.

Operation is restricted to super_user roles only

operation (required) - this should always be drop_database
database (required) - name of the database you are dropping
replicated (optional) - if true, HarperDB will replicate the component to all nodes in the cluster. Must be a boolean.

Body

{
    "operation": "drop_database",
    "database": "dev"
}

Response: 200

{
    "message": "successfully deleted 'dev'"
}

Create Table

Create a new table within a database.

Operation is restricted to super_user roles only

operation (required) - must always be create_table
database (optional) - name of the database where you want your table to live. If the database does not exist, it will be created. If the database property is not provided it will default to data.
table (required) - name of the table you are creating
primary_key (required) - primary key for the table
attributes (optional) - an array of attributes that specifies the schema for the table, that is the set of attributes for the table. When attributes are supplied the table will not be considered a "dynamic schema" table, and attributes will not be auto-added when records with new properties are inserted. Each attribute is specified as:
- name (required) - the name of the attribute
- indexed (optional) - indicates if the attribute should be indexed
- type (optional) - specifies the data type of the attribute (can be String, Int, Float, Date, ID, Any)
expiration (optional) - specifies the time-to-live or expiration of records in the table before they are evicted (records are not evicted on any timer if not specified). This is specified in seconds.

Body

{
    "operation": "create_table",
    "database": "dev",
    "table": "dog",
    "primary_key": "id"
}

Response: 200

{
    "message": "table 'dev.dog' successfully created."
}

Drop Table

Drop an existing database table. NOTE: Dropping a table will delete all associated records in that table.

Operation is restricted to super_user roles only

operation (required) - this should always be drop_table
database (optional) - database where the table you are dropping lives. The default is data
table (required) - name of the table you are dropping
replicated (optional) - if true, HarperDB will replicate the component to all nodes in the cluster. Must be a boolean.

Body

{
    "operation": "drop_table",
    "database": "dev",
    "table": "dog"
}

Response: 200

{
    "message": "successfully deleted table 'dev.dog'"
}

Create Attribute

Create a new attribute within the specified table. The create_attribute operation can be used for admins wishing to pre-define database values for setting role-based permissions or for any other reason.

Note: HarperDB will automatically create new attributes on insert and update if they do not already exist within the database.

operation (required) - must always be create_attribute
database (optional) - name of the database of the table you want to add your attribute. The default is data
table (required) - name of the table where you want to add your attribute to live
attribute (required) - name for the attribute

Body

{
    "operation": "create_attribute",
    "database": "dev",
    "table": "dog",
    "attribute": "is_adorable"
}

Response: 200

{
    "message": "inserted 1 of 1 records",
    "skipped_hashes": [],
    "inserted_hashes": [
        "383c0bef-5781-4e1c-b5c8-987459ad0831"
    ]
}

Drop Attribute

Drop an existing attribute from the specified table. NOTE: Dropping an attribute will delete all associated attribute values in that table.

Operation is restricted to super_user roles only

operation (required) - this should always be drop_attribute
database (optional) - database where the table you are dropping lives. The default is data
table (required) - table where the attribute you are dropping lives
attribute (required) - attribute that you intend to drop

Body

{
    "operation": "drop_attribute",
    "database": "dev",
    "table": "dog",
    "attribute": "is_adorable"
}

Response: 200

{
    "message": "successfully deleted attribute 'is_adorable'"
}

Get Backup

This will return a snapshot of the requested database. This provides a means for backing up the database through the operations API. The response will be the raw database file (in binary format), which can later be restored as a database file by copying into the appropriate hdb/databases directory (with HarperDB not running). The returned file is a snapshot of the database at the moment in time that the get_backup operation begins. This also supports backing up individual tables in a database. However, this is a more expensive operation than backing up a database in whole, and will lose any transactional atomicity between writes across tables, so generally it is recommended that you backup the entire database.

It is important to note that trying to copy a database file that is in use (HarperDB actively running and writing to the file) using standard file copying tools is not safe (the copied file will likely be corrupt), which is why using this snapshot operation is recommended for backups (volume snapshots are also a good way to backup HarperDB databases).

Operation is restricted to super_user roles only

operation (required) - this should always be get_backup
database (required) - this is the database that will be snapshotted and returned
table (optional) - this will specify a specific table to backup
tables (optional) - this will specify a specific set of tables to backup

Body

{
    "operation": "get_backup",
    "database": "dev"
}

Response: 200

The database in raw binary data format

PreviousQuick Start Examples NextNoSQL Operations

Last updated 1 month ago