Deprecations and migrations

This page lists compatibility behavior and changes that affect existing applications and deployments. The command reference and examples describe the current API. The lists below distinguish compatibility syntax that still works from features that have been removed. GetApiSchema favors current spellings: it omits DiagnosticTool, deprecated result selectors, and legacy constraint syntax. Some compatibility fields, including GetStatus.cpu_utilization, remain in the schema. Schema presence alone does not establish that a field is recommended or fully implemented; use the command reference and migrations below.

Deprecated features

These features remain accepted for compatibility. Use the replacements in new code and when updating existing applications.

Deprecated feature	Replacement
Property-keyed constraint objects, including object-form groups	Use Array expressions, including in connection filters and if_not_found. For example, replace {"age": [">=", 18]} with ["$age", ">=", 18]. Legacy object-form groups are not accepted by if_not_found; conditional adds support nested groups through array expressions.
sort, limit, group_by_source, or uniqueids inside results	Put these parameters at the command level. See sort, limit, group_by_source, and uniqueids.
Comments in JSON requests	Send standard JSON without comments. Keep explanations outside the request payload.
index_type and property_key in index commands	Use target and property in CreateIndex, GetIndexes, and RemoveIndex. Do not send both spellings of the same selector in one command.
Omitting kind from CreateIndex or RemoveIndex	Specify kind explicitly, for example "kind": "ordered". The implicit ordered default is scheduled for removal in 1.0.0.
Descriptor engines FaissFlat, FaissIVFFlat, and FaissHNSWFlat	Use Flat, IVF, and HNSW, respectively. This applies to AddDescriptorSet, UpdateDescriptorSet, FindDescriptor, and FindDescriptorBatch. See descriptor engines.
DiagnosticTool	There is no general replacement command. Use the documented administration interfaces for your task; contact support for database repair procedures.
enable_dfs configuration option	Select storage with storage_type (ext4, s3, or gs), storage_bucket_name, and storage_credentials. The old option is accepted but has no effect. See Configuration File.
GetStatus.cpu_utilization	Use host or container CPU monitoring. This compatibility field always returns zero and does not measure CPU use.

Descriptor engine names are case-sensitive. New or updated engine values are stored using the current names. Existing stored aliases remain readable without a manual metadata migration. Omitting an engine when creating a descriptor set still selects IVF; this default is supported.

Accepted options without effect

The following fields remain accepted but do not affect the response or server behavior. They can be removed from existing requests and configuration files.

Field	Behavior
collect_thread_interval and collect_interval_set	Accepted configuration fields with no active collection behavior.
sys_status_periodic_log	Accepted but does not enable periodic status logging.

Finding deprecated usage

Use the deprecated_usage_total counter from GetMetrics to identify compatibility features used by your applications. The feature label identifies the feature. Counts accumulate until the server process restarts; reading metrics does not reset them. A request can increment more than one counter, including requests that later fail.

Feature label	What it counts
constraints_object	Property-keyed constraint objects, including conditional and nested filters and object-form groups.
results_sort	Sorting specified inside results.
json_comments	JSON parsed with comments.
index_type_field / property_key_field	Index commands using the old selector names.
createindex_implicit_kind / removeindex_implicit_kind	Index creation or removal without an explicit kind.
descriptor_engine_faiss_flat	Resolutions of FaissFlat.
descriptor_engine_faiss_ivf_flat	Resolutions of FaissIVFFlat.
descriptor_engine_faiss_hnsw_flat	Resolutions of FaissHNSWFlat.
diagnostic_tool	Uses of DiagnosticTool.

These counters do not cover every feature listed above. Descriptor engine counters include command execution and reads of stored descriptor-set metadata, including background refreshes. They count alias resolutions, rather than unique requests or descriptor sets.

The Grafana Deprecations dashboard shows usage rates and cumulative counts for currently scraped processes. Cumulative counts include uses first observed at startup; rates cannot capture those uses without an earlier sample.

This metric family is included in the default JSON and Prometheus responses. To request only deprecation metrics:

[{
    "GetMetrics": {
        "metrics": [{"family": "deprecated_usage_total"}]
    }
}]

Removed features and response changes

These forms are not part of the current API. Dated changes cover 0.19.13 onward, newest first, matching Release Notes. Entries without a version describe current requirements without assigning a removal release.

Previous feature or format	Migration
Flat GetUsers and GetRoles responses (0.20.0)	Read named entries from users and roles, respectively. status and returned are alongside that object. See GetUsers and GetRoles.
Named remote credentials (0.20.0)	Identify credentials by origin and replace the complete key when updating. GetCredentials lists origins without returning keys. See Remote credentials for request changes and upgrade behavior.
session_cache_max_age_sec and sessions_file_refresh_rate_sec (0.20.0)	Remove these configuration fields; they are rejected. See Configuration File for current session settings.
Authenticate or RefreshToken alongside other commands (0.20.0)	Submit each as a single-command query, then use the returned session token for subsequent queries.
GetSchema property arrays [matched, indexed, type] (0.19.15)	Read an object containing count and type. Retrieve index information separately with GetIndexes.
GetIndexes.entities and GetIndexes.connections (0.19.15)	Read indexes and returned. See GetIndexes.
commits_between_checkpoints (0.19.15)	Use seconds_between_checkpoints. Scheduled checkpoints run when there are pending changes.
Index type options bool, number, date, and text: false (0.19.14)	Use "kind": "ordered" for scalar indexing. Ordered indexes cover all supported scalar types. See CreateIndex for other kinds and their parameters.
Index identifiers returned as index_id (0.19.14)	Identify an index by target, class, property, and kind. CreateIndex returns a success status; inspect definitions with GetIndexes. Remove and recreate an index to change its parameters.
Numeric code for the media flip operation (0.19.13)	Use mode with horizontal, vertical, or both. See operations.
_object property wrapper	Use _json to store a JSON value. See properties.
date or _date wrappers as expression operands	Use to_date in Array expressions. Property writes still use _date to store datetimes. Keys inside a json literal remain ordinary JSON data.
blobs_path, images_path, videos_path, and descriptors_path	These configuration fields are rejected. Configure db_root_path instead; see Configuration File.
Helm appVersion and webuiVersion value overrides	Select the chart version. Published charts pin the database and Web UI images together. appVersion overrides are rejected; webuiVersion does not select an image version. See Deploy with Helm.
OpenTofu app_version and webui_version input overrides	Select the module package tag. These inputs are not available; the app_version output remains supported. See Deploy with OpenTofu.
tdb image format	Use jpg, png, or tif for image format parameters. See format and FindImage.
Tools image aperturedata/aperturedb-tools and scan_changelogs spelling	Use aperturedata/tools with the database’s release tag and the scan-changelogs executable.

Deployment recipes

Earlier setup pages included hand-maintained Docker Compose recipes, including start_files/docker-compose.yml and the notebook setup example. Those recipes are not the configuration for the published Compose packages.

Use the layouts and environment settings in Deploy with Docker Compose. The package contains coordinated service images and configuration. Transfer storage settings, credentials, published ports, and TLS settings through the package’s documented environment variables rather than copying an old service configuration unchanged.

Database upgrades

For a supported upgrade to 0.20.0, existing users, roles, personal tokens, and usable remote credentials are imported. Existing sessions and refresh tokens are not retained, so sign in again. Afterward, manage security settings through the API; editing the old access-control files no longer changes access. Review imported origins and test media reads as described in Remote credentials. See Access Control for current session rules.

Databases from 0.19.13 must complete the 0.19.14 upgrade before moving to 0.19.15 or later. Those later releases do not include the 0.19.14 conversion. Startup rejects incompatible databases; preserve their data and logs and contact support instead of deleting files to force an upgrade.

Upgrade procedure

1. Record the server version from GetStatus, client versions, deployment package tag, configuration, and storage locations. Read Release Notes and this page for every intermediate release in the upgrade path. Update applications that consume changed request or response formats before changing production.

2. Stop application writes and take a verified, restorable backup. Preserve database and object data, required coordination state, credentials, configuration, package references, and OpenTofu state when applicable. A chart rollback or an older image is not a database backup.

3. Rehearse the upgrade and representative reads and writes on an isolated restore. Preserve deployment identity and storage locations. Allow for service interruption; the deployment guides do not establish a zero-downtime or mixed-version upgrade guarantee.

4. After each required upgrade step, inspect logs and validate application queries and schema consumers. Connect and verify the deployment describes connection checks. Resume writes only after validation succeeds.

If validation fails, keep writes stopped and preserve logs. Restore the pre-upgrade backup with its matching software and configuration; downgrading binaries does not establish that storage conversions have been reversed.