Deprecations and migrations

Use this page when updating an existing application or deployment. 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 describes the current API and omits deprecated commands and syntax, even when the server still accepts them for compatibility.

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].
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.

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. Version numbers below identify changes recorded in Release Notes; entries without a version describe the current behavior without assigning a removal release.

Previous feature or format	Migration
arrange_by_group (0.19.11)	Use per_group to sort and paginate each source group.
storage_directory_count (0.19.12)	Remove this option from configuration files.
Numeric code for the media flip operation (0.19.13)	Use mode with horizontal, vertical, or both. See operations.
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.
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.
_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.

Database upgrades

Databases from 0.19.13 must complete the 0.19.14 upgrade before moving to 0.19.15. The automatic conversion provided by 0.19.14 is not included in 0.19.15, which rejects incompatible databases at startup.