Skip to main content
Version: v4

Operations Reference

This page lists all available Operations API operations, grouped by category. Each entry links to the feature section where the full documentation lives.

For endpoint and authentication setup, see the Operations API Overview.

Databases & Tables​

Operations for managing databases, tables, and attributes.

Detailed documentation: Database Overview

OperationDescriptionRole Required
describe_allReturns definitions of all databases and tables, with record countsany
describe_databaseReturns all table definitions for a specified databaseany
describe_tableReturns the definition of a specified tableany
create_databaseCreates a new databasesuper_user
drop_databaseDrops a database and all its tables/recordssuper_user
create_tableCreates a new table with optional schema and expirationsuper_user
drop_tableDrops a table and all its recordssuper_user
create_attributeAdds a new attribute to a tablesuper_user
drop_attributeRemoves an attribute and all its values from a tablesuper_user
get_backupReturns a binary snapshot of a database for backup purposessuper_user

describe_all​

Returns the definitions of all databases and tables within the database. Record counts above 5000 records are estimated; the response includes estimated_record_range when estimated. To force an exact count (requires full table scan), include "exact_count": true.

{ "operation": "describe_all" }

describe_database​

Returns all table definitions within the specified database.

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

describe_table​

Returns the definition of a specific table.

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

create_database​

Creates a new database.

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

drop_database​

Drops a database and all its tables/records. Supports "replicated": true to propagate to all cluster nodes.

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

create_table​

Creates a new table. Optional fields: database (defaults to data), attributes (array defining schema), expiration (TTL in seconds).

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

drop_table​

Drops a table and all associated records. Supports "replicated": true.

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

create_attribute​

Creates a new attribute within a table. Harper auto-creates attributes on insert/update, but this can be used to pre-define them (e.g., for role-based permission setup).

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

drop_attribute​

Drops an attribute and all its values from the specified table.

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

get_backup​

Returns a binary snapshot of the specified database (or individual table). Safe for backup while Harper is running. Specify "table" for a single table or "tables" for a set.

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

NoSQL Operations​

Operations for inserting, updating, deleting, and querying records using NoSQL.

Detailed documentation: REST Querying Reference

OperationDescriptionRole Required
insertInserts one or more recordsany
updateUpdates one or more records by primary keyany
upsertInserts or updates recordsany
deleteDeletes records by primary keyany
search_by_idRetrieves records by primary keyany
search_by_valueRetrieves records matching a value on any attributeany
search_by_conditionsRetrieves records matching complex conditions with sorting and paginationany

insert​

Inserts one or more records. If a primary key is not provided, a GUID or auto-increment value is generated.

{
	"operation": "insert",
	"database": "dev",
	"table": "dog",
	"records": [{ "id": 1, "dog_name": "Penny" }]
}

update​

Updates one or more records. Primary key must be supplied for each record.

{
	"operation": "update",
	"database": "dev",
	"table": "dog",
	"records": [{ "id": 1, "weight_lbs": 38 }]
}

upsert​

Updates existing records and inserts new ones. Matches on primary key if provided.

{
	"operation": "upsert",
	"database": "dev",
	"table": "dog",
	"records": [{ "id": 1, "weight_lbs": 40 }]
}

delete​

Deletes records by primary key values.

{
	"operation": "delete",
	"database": "dev",
	"table": "dog",
	"ids": [1, 2]
}

search_by_id​

Returns records matching the given primary key values. Use "get_attributes": ["*"] to return all attributes.

{
	"operation": "search_by_id",
	"database": "dev",
	"table": "dog",
	"ids": [1, 2],
	"get_attributes": ["dog_name", "breed_id"]
}

search_by_value​

Returns records with a matching value on any attribute. Supports wildcards (e.g., "Ky*").

{
	"operation": "search_by_value",
	"database": "dev",
	"table": "dog",
	"attribute": "owner_name",
	"value": "Ky*",
	"get_attributes": ["id", "dog_name"]
}

search_by_conditions​

Returns records matching one or more conditions. Supports operator (and/or), offset, limit, nested conditions groups, and sort with multi-level tie-breaking.

{
	"operation": "search_by_conditions",
	"database": "dev",
	"table": "dog",
	"operator": "and",
	"limit": 10,
	"get_attributes": ["*"],
	"conditions": [{ "attribute": "age", "comparator": "between", "value": [5, 8] }]
}

Bulk Operations​

Operations for bulk import/export of data.

Detailed documentation: Database Jobs

OperationDescriptionRole Required
export_localExports query results to a local file in JSON or CSVsuper_user
csv_data_loadIngests CSV data provided inlineany
csv_file_loadIngests CSV data from a server-local file pathany
csv_url_loadIngests CSV data from a URLany
export_to_s3Exports query results to AWS S3super_user
import_from_s3Imports CSV or JSON data from AWS S3any
delete_records_beforeDeletes records older than a given timestamp (local node only)super_user

All bulk import/export operations are asynchronous and return a job ID. Use get_job to check status.

export_local​

Exports query results to a local path on the server. Formats: json or csv.

{
	"operation": "export_local",
	"format": "json",
	"path": "/data/",
	"search_operation": { "operation": "sql", "sql": "SELECT * FROM dev.dog" }
}

csv_data_load​

Ingests inline CSV data. Actions: insert (default), update, upsert.

{
	"operation": "csv_data_load",
	"database": "dev",
	"table": "dog",
	"action": "insert",
	"data": "id,name\n1,Penny\n"
}

csv_file_load​

Ingests CSV from a file path on the server running Harper.

{
	"operation": "csv_file_load",
	"database": "dev",
	"table": "dog",
	"file_path": "/home/user/imports/dogs.csv"
}

csv_url_load​

Ingests CSV from a URL.

{
	"operation": "csv_url_load",
	"database": "dev",
	"table": "dog",
	"csv_url": "https://example.com/dogs.csv"
}

export_to_s3​

Exports query results to an AWS S3 bucket as JSON or CSV.

{
	"operation": "export_to_s3",
	"format": "json",
	"s3": {
		"aws_access_key_id": "YOUR_KEY",
		"aws_secret_access_key": "YOUR_SECRET",
		"bucket": "my-bucket",
		"key": "dogs.json",
		"region": "us-east-1"
	},
	"search_operation": { "operation": "sql", "sql": "SELECT * FROM dev.dog" }
}

import_from_s3​

Imports CSV or JSON from an AWS S3 bucket. File must include a valid .csv or .json extension.

{
	"operation": "import_from_s3",
	"database": "dev",
	"table": "dog",
	"s3": {
		"aws_access_key_id": "YOUR_KEY",
		"aws_secret_access_key": "YOUR_SECRET",
		"bucket": "my-bucket",
		"key": "dogs.csv",
		"region": "us-east-1"
	}
}

delete_records_before​

Deletes records older than the specified timestamp from the local node only. Clustered nodes retain their data.

{
	"operation": "delete_records_before",
	"date": "2021-01-25T23:05:27.464",
	"schema": "dev",
	"table": "dog"
}

SQL Operations​

Operations for executing SQL statements.

warning

Harper SQL is intended for data investigation and use cases where performance is not a priority. For production workloads, use NoSQL or REST operations. SQL performance optimizations are on the roadmap.

Detailed documentation: SQL Reference

OperationDescriptionRole Required
sqlExecutes a SQL SELECT, INSERT, UPDATE, or DELETE statementany

sql​

Executes a standard SQL statement.

{ "operation": "sql", "sql": "SELECT * FROM dev.dog WHERE id = 1" }

Users & Roles​

Operations for managing users and role-based access control (RBAC).

Detailed documentation: Users & Roles Operations

OperationDescriptionRole Required
list_rolesReturns all rolessuper_user
add_roleCreates a new role with permissionssuper_user
alter_roleModifies an existing role's permissionssuper_user
drop_roleDeletes a role (role must have no associated users)super_user
list_usersReturns all userssuper_user
user_infoReturns data for the authenticated userany
add_userCreates a new usersuper_user
alter_userModifies an existing user's credentials or rolesuper_user
drop_userDeletes a usersuper_user

list_roles​

Returns all roles defined in the instance.

{ "operation": "list_roles" }

add_role​

Creates a new role with the specified permissions. The permission object maps database names to table-level access rules (read, insert, update, delete). Set super_user: true to grant full access.

{
	"operation": "add_role",
	"role": "developer",
	"permission": {
		"super_user": false,
		"dev": {
			"tables": {
				"dog": { "read": true, "insert": true, "update": true, "delete": false }
			}
		}
	}
}

alter_role​

Modifies an existing role's name or permissions. Requires the role's id (returned by list_roles).

{
	"operation": "alter_role",
	"id": "f92162e2-cd17-450c-aae0-372a76859038",
	"role": "senior_developer",
	"permission": {
		"super_user": false,
		"dev": {
			"tables": {
				"dog": { "read": true, "insert": true, "update": true, "delete": true }
			}
		}
	}
}

drop_role​

Deletes a role. The role must have no associated users before it can be dropped.

{ "operation": "drop_role", "id": "f92162e2-cd17-450c-aae0-372a76859038" }

list_users​

Returns all users.

{ "operation": "list_users" }

user_info​

Returns data for the currently authenticated user.

{ "operation": "user_info" }

add_user​

Creates a new user. username cannot be changed after creation. password is stored encrypted.

{
	"operation": "add_user",
	"role": "developer",
	"username": "hdb_user",
	"password": "password",
	"active": true
}

alter_user​

Modifies an existing user's password, role, or active status. All fields except username are optional.

{
	"operation": "alter_user",
	"username": "hdb_user",
	"password": "new_password",
	"role": "senior_developer",
	"active": true
}

drop_user​

Deletes a user by username.

{ "operation": "drop_user", "username": "hdb_user" }

See Users & Roles Operations for full documentation including permission object structure.

Token Authentication​

Operations for JWT token creation and refresh.

Detailed documentation: JWT Authentication

OperationDescriptionRole Required
create_authentication_tokensCreates an operation token and refresh token for a usernone (unauthenticated)
refresh_operation_tokenCreates a new operation token from a refresh tokenany

create_authentication_tokens​

Does not require prior authentication. Returns operation_token (short-lived JWT) and refresh_token (long-lived JWT).

{
	"operation": "create_authentication_tokens",
	"username": "my-user",
	"password": "my-password"
}

refresh_operation_token​

Creates a new operation token from an existing refresh token.

{
	"operation": "refresh_operation_token",
	"refresh_token": "EXISTING_REFRESH_TOKEN"
}

Components​

Operations for deploying and managing Harper components (applications, extensions, plugins).

Detailed documentation: Components Overview

OperationDescriptionRole Required
add_componentCreates a new component project from a templatesuper_user
deploy_componentDeploys a component via payload (tar) or package reference (NPM/GitHub)super_user
package_componentPackages a component project into a base64-encoded tarsuper_user
drop_componentDeletes a component or a file within a componentsuper_user
get_componentsLists all component files and configsuper_user
get_component_fileReturns the contents of a file within a componentsuper_user
set_component_fileCreates or updates a file within a componentsuper_user
add_ssh_keyAdds an SSH key for deploying from private repositoriessuper_user
update_ssh_keyUpdates an existing SSH keysuper_user
delete_ssh_keyDeletes an SSH keysuper_user
list_ssh_keysLists all configured SSH key namessuper_user
set_ssh_known_hostsOverwrites the SSH known_hosts filesuper_user
get_ssh_known_hostsReturns the contents of the SSH known_hosts filesuper_user
install_node_modules(Deprecated) Run npm install on component projectssuper_user

deploy_component​

Deploys a component. The package option accepts any valid NPM reference including GitHub repos (HarperDB/app#semver:v1.0.0), tarballs, or NPM packages. The payload option accepts a base64-encoded tar string from package_component. Supports "replicated": true and "restart": true or "restart": "rolling".

{
	"operation": "deploy_component",
	"project": "my-app",
	"package": "my-org/my-app#semver:v1.2.3",
	"replicated": true,
	"restart": "rolling"
}

add_ssh_key​

Adds an SSH key (must be ed25519) for authenticating deployments from private repositories.

{
	"operation": "add_ssh_key",
	"name": "my-key",
	"key": "-----BEGIN OPENSSH PRIVATE KEY-----\n...\n-----END OPENSSH PRIVATE KEY-----\n",
	"host": "my-key.github.com",
	"hostname": "github.com"
}

Replication & Clustering​

Operations for configuring and managing Harper cluster replication.

Detailed documentation: Replication & Clustering

OperationDescriptionRole Required
add_nodeAdds a Harper instance to the clustersuper_user
update_nodeModifies an existing node's subscriptionssuper_user
remove_nodeRemoves a node from the clustersuper_user
cluster_statusReturns current cluster connection statussuper_user
configure_clusterBulk-creates/resets cluster subscriptions across multiple nodessuper_user
cluster_set_routesAdds routes to the replication routes config (PATCH/upsert)super_user
cluster_get_routesReturns the current replication routes configsuper_user
cluster_delete_routesRemoves routes from the replication routes configsuper_user

add_node​

Adds a remote Harper node to the cluster. If subscriptions are not provided, a fully replicating cluster is created. Optional fields: verify_tls, authorization, retain_authorization, revoked_certificates, shard.

{
	"operation": "add_node",
	"hostname": "server-two",
	"verify_tls": false,
	"authorization": { "username": "admin", "password": "password" }
}

cluster_status​

Returns connection state for all cluster nodes, including per-database socket status and replication timing statistics (lastCommitConfirmed, lastReceivedRemoteTime, lastReceivedLocalTime).

{ "operation": "cluster_status" }

configure_cluster​

Resets and replaces the entire clustering configuration. Each entry follows the add_node schema.

{
	"operation": "configure_cluster",
	"connections": [
		{
			"hostname": "server-two",
			"subscriptions": [{ "database": "dev", "table": "dog", "subscribe": true, "publish": true }]
		}
	]
}

Configuration​

Operations for reading and updating Harper configuration.

Detailed documentation: Configuration Overview

OperationDescriptionRole Required
set_configurationModifies Harper configuration file parameters (requires restart)super_user
get_configurationReturns the current Harper configurationsuper_user

set_configuration​

Updates configuration parameters in harperdb-config.yaml. A restart (restart or restart_service) is required for changes to take effect.

{
	"operation": "set_configuration",
	"logging_level": "trace",
	"clustering_enabled": true
}

get_configuration​

Returns the full current configuration object.

{ "operation": "get_configuration" }

System​

Operations for restarting Harper and managing system state.

OperationDescriptionRole Required
restartRestarts the Harper instancesuper_user
restart_serviceRestarts a specific Harper servicesuper_user
system_informationReturns detailed host system metricssuper_user
set_statusSets an application-specific status value (in-memory)super_user
get_statusReturns a previously set status valuesuper_user
clear_statusRemoves a status entrysuper_user

restart​

Restarts all Harper processes. May take up to 60 seconds.

{ "operation": "restart" }

restart_service​

Restarts a specific service. service must be one of: http_workers, clustering_config, clustering. Supports "replicated": true for a rolling cluster restart.

{ "operation": "restart_service", "service": "http_workers" }

system_information​

Returns system metrics including CPU, memory, disk, network, and Harper process info. Optionally filter by attributes array (e.g., ["cpu", "memory", "replication"]).

{ "operation": "system_information" }

set_status / get_status / clear_status​

Manage in-memory application status values. Status types: primary, maintenance, availability (availability only accepts 'Available' or 'Unavailable'). Status is not persisted across restarts.

{ "operation": "set_status", "id": "primary", "status": "active" }

Jobs​

Operations for querying background job status.

Detailed documentation: Database Jobs

OperationDescriptionRole Required
get_jobReturns status and results for a specific job IDany
search_jobs_by_start_dateReturns jobs within a specified time windowsuper_user

get_job​

Returns job status (COMPLETE, IN_PROGRESS, ERROR), timing, and result message for the specified job ID. Bulk import/export operations return a job ID on initiation.

{ "operation": "get_job", "id": "4a982782-929a-4507-8794-26dae1132def" }

search_jobs_by_start_date​

Returns all jobs started within the specified datetime range.

{
	"operation": "search_jobs_by_start_date",
	"from_date": "2021-01-25T22:05:27.464+0000",
	"to_date": "2021-01-25T23:05:27.464+0000"
}

Logs​

Operations for reading Harper logs.

Detailed documentation: Logging Operations

OperationDescriptionRole Required
read_logReturns entries from the primary hdb.logsuper_user
read_transaction_logReturns transaction history for a tablesuper_user
delete_transaction_logs_beforeDeletes transaction log entries older than a timestampsuper_user
read_audit_logReturns verbose audit history for a table (requires audit log enabled)super_user
delete_audit_logs_beforeDeletes audit log entries older than a timestampsuper_user

read_log​

Returns entries from hdb.log. Filter by level (notify, error, warn, info, debug, trace), date range (from, until), and text filter.

{
	"operation": "read_log",
	"start": 0,
	"limit": 100,
	"level": "error"
}

read_transaction_log​

Returns transaction history for a specific table. Optionally filter by from/to (millisecond epoch) and limit.

{
	"operation": "read_transaction_log",
	"schema": "dev",
	"table": "dog",
	"limit": 10
}

read_audit_log​

Returns verbose audit history including original record state. Requires logging.auditLog: true in configuration. Filter by search_type: hash_value, timestamp, or username.

{
	"operation": "read_audit_log",
	"schema": "dev",
	"table": "dog",
	"search_type": "username",
	"search_values": ["admin"]
}

Certificate Management​

Operations for managing TLS certificates in the hdb_certificate system table.

Detailed documentation: Certificate Management

OperationDescriptionRole Required
add_certificateAdds or updates a certificatesuper_user
remove_certificateRemoves a certificate and its private key filesuper_user
list_certificatesLists all certificatessuper_user

add_certificate​

Adds a certificate to hdb_certificate. If a private_key is provided, it is written to <rootPath>/keys/ (not stored in the table). If no private key is provided, the operation searches for a matching one on disk.

{
	"operation": "add_certificate",
	"name": "my-cert",
	"certificate": "-----BEGIN CERTIFICATE-----...",
	"is_authority": false,
	"private_key": "-----BEGIN RSA PRIVATE KEY-----..."
}

Analytics​

Operations for querying analytics metrics.

Detailed documentation: Analytics Operations

OperationDescriptionRole Required
get_analyticsRetrieves analytics data for a specified metricany
list_metricsLists available analytics metricsany
describe_metricReturns the schema of a specific metricany

get_analytics​

Retrieves analytics data. Supports start_time/end_time (Unix ms), get_attributes, and conditions (same format as search_by_conditions).

{
	"operation": "get_analytics",
	"metric": "resource-usage",
	"start_time": 1769198332754,
	"end_time": 1769198532754
}

list_metrics​

Returns available metric names. Filter by metric_types: custom, builtin (default: builtin).

{ "operation": "list_metrics" }

Registration & Licensing​

Operations for license management.

OperationDescriptionRole Required
registration_infoReturns registration and version informationany
install_usage_licenseInstalls a Harper usage license blocksuper_user
get_usage_licensesReturns all usage licenses with consumption countssuper_user
get_fingerprint(Deprecated) Returns the machine fingerprintsuper_user
set_license(Deprecated) Sets a license keysuper_user

registration_info​

Returns the instance registration status, version, RAM allocation, and license expiration.

{ "operation": "registration_info" }

install_usage_license​

Installs a usage license block. A license is a JWT-like structure (header.payload.signature) signed by Harper. Multiple blocks may be installed; earliest blocks are consumed first.

{
	"operation": "install_usage_license",
	"license": "abc...0123.abc...0123.abc...0123"
}

get_usage_licenses​

Returns all usage licenses (including expired/exhausted) with current consumption counts. Optionally filter by region.

{ "operation": "get_usage_licenses" }

Deprecated Operations​

The following operations are deprecated and should not be used in new code.

Custom Functions (Deprecated)​

Custom Functions were the precursor to the Component architecture introduced in v4.2.0. These operations are preserved for backward compatibility.

Deprecated in: v4.2.0 (moved to legacy in v4.7+)

For modern equivalents, see Components Overview.

OperationDescription
custom_functions_statusReturns Custom Functions server status
get_custom_functionsLists all Custom Function projects
get_custom_functionReturns a Custom Function file's content
set_custom_functionCreates or updates a Custom Function file
drop_custom_functionDeletes a Custom Function file
add_custom_function_projectCreates a new Custom Function project
drop_custom_function_projectDeletes a Custom Function project
package_custom_function_projectPackages a Custom Function project as base64 tar
deploy_custom_function_projectDeploys a packaged Custom Function project

Other Deprecated Operations​

OperationReplaced By
install_node_modulesHandled automatically by deploy_component and restart
get_fingerprintUse registration_info
set_licenseUse install_usage_license
search_by_hashUse search_by_id
search_attributeUse attribute field in search_by_value / search_by_conditions
search_valueUse value field in search_by_value / search_by_conditions
search_typeUse comparator field in search_by_conditions