Skip to main content

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.

Preparing for 1.0.0​

0.20.0 reports the compatibility paths that 1.0.0 removes through deprecated_usage_total and the Grafana Deprecations dashboard. Upgrade every database to 0.20.0 and let startup complete before upgrading to 1.0.0. Use both current rates and cumulative counts while exercising representative traffic, SDK helpers, CSV loaders, administration scripts, and scheduled jobs. Check every server process. No data is not a zero count: verify successful scrapes and the presence of the feature labels listed below.

Array constraints, top-level result options, explicit index kind, canonical engine names, explicit FindDescriptor/FindDescriptorBatch KNN engines, the descriptor-set engines object, an explicit ClassifyDescriptor engine, and filtered_knn can be adopted on 0.20.0. These 1.0.0 request forms are accepted here without being counted, so an application migrated on 0.20.0 keeps working after the upgrade.

1.0.0 returns FindDescriptorSet._engines as a configuration object and no longer reports _engine_params. Send "engines_format": "object" to receive that form on 0.20.0 as well; see FindDescriptorSet. 1.0.0 accepts the same request. The 0.20.0 array form and _engine_params remain available and are not counted as deprecated usage.

Lazy indexing and the new ACORN engine need 1.0.0: 0.20.0 rejects lazy_indexing: true and the acorn key in engines. Configure them with UpdateDescriptorSet.engines after upgrading.

The automatic ordered indexes on _DescriptorSet._name, _Descriptor._set_name, and _Descriptor._create_txn are retired during upgrade; the properties remain available. Rehearse representative queries and create supported property indexes explicitly where needed.

Counters identify observed requests and responses, not a complete upgrade certification. A zero rate can reflect an idle workload; cumulative counts reset on process restart. getstatus_cpu_utilization_response counts responses and cannot tell whether a client actually reads the field. diagnostic_tool can stay nonzero before upgrade because DiagnosticTool has no replacement. Review the affected consumers, preserve their intended behavior, and follow the Database upgrades rehearsal and backup procedure before upgrading.

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.

AddDescriptorSet.engine or an omitted engine; UpdateDescriptorSet.engine; engine_params

Use the engines object, with lowercase flat, ivf, and hnsw keys and each engine’s settings in its entry. Creation requires a nonempty object; updates replace the whole engine configuration. Parameter names, types, and ranges follow the 1.0.0 rules.

ClassifyDescriptor without engine

Name a configured engine with engine, which 1.0.0 requires.

acorn in FindDescriptor and FindDescriptorBatch

Use filtered_knn, the 1.0.0 name with the same behavior. Do not send both, even when false.

indexed_results_only in FindDescriptor and FindDescriptorBatch

Remove it. 1.0.0 has no replacement: its searches always include descriptors that are not yet indexed, as 0.20.0 searches do without this parameter.

segment_size and max_segments in AddDescriptorSet and UpdateDescriptorSet

Remove them. They are accepted without effect and no longer change how descriptors are partitioned.

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, and 1.0.0 removes it. 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 in 0.20.0; 1.0.0 requires explicit engine configuration.

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.

segment_size and max_segments in descriptor-set commands

Accepted and counted as deprecated, but no longer stored or applied.

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.

results_limit / results_group_by_source / results_uniqueids

These selectors explicitly supplied inside results, including false boolean values. Move them to the command level. Selecting _uniqueid through results.list is supported and is not counted.

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

Requests for DiagnosticTool, including requests refused because debug commands are disabled.

descriptor_set_engine_field

AddDescriptorSet or UpdateDescriptorSet using engine, whether scalar or array (including an empty array). Use the engines object.

descriptor_set_engine_params

Descriptor-set commands supplying engine_params. Move these settings into the engines object.

adddescriptorset_implicit_engine

Creating a descriptor set with an omitted or empty engine selection and no engines object. 1.0.0 requires a nonempty engines object.

descriptor_knn_implicit_engine

FindDescriptor or FindDescriptorBatch KNN requests without an explicit engine. Supply a canonical engine name on 0.20.0 and 1.0.0.

classifydescriptor_implicit_engine

ClassifyDescriptor requests without engine. Supply a canonical engine name on 0.20.0 and 1.0.0.

descriptor_acorn / descriptor_indexed_results_only

Requests supplying these removed parameters, including false values. Replace acorn with filtered_knn and remove indexed_results_only.

descriptor_set_segment_size / descriptor_set_max_segments

Descriptor-set commands supplying these ignored fields. Remove them.

getstatus_cpu_utilization

Explicit requests for GetStatus.cpu_utilization, even when false. Remove the field and use host/container CPU monitoring.

getstatus_cpu_utilization_response

Responses actually emitting cpu_utilization, including requests with all: true. This counts exposure, not confirmed client use.

config_enable_dfs

Configuration-file loads containing enable_dfs. Remove it and select storage with the current storage configuration fields.

config_collect_thread_interval / config_collect_interval_set / config_sys_status_periodic_log

Configuration-file loads containing these unused fields. Remove them before 1.0.0. Counts include startup and explicit false values.

Descriptor engine alias 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 1.0.0 upgrade converts stored aliases. To clear these counts before upgrading, send each affected set’s complete configuration with UpdateDescriptorSet.engines, which stores the canonical names.

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.

resources_max_mem_limit, resources_check_mem_limit, resources_check_sleep, and resources_check_kill_timer (0.20.0)

Remove these configuration fields; they are rejected. The server no longer cancels or rejects queries because of memory use.

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.

0.20.0 upgrades databases directly from 0.19.14, 0.19.15, or 0.19.16. When upgrading from 0.19.14 or 0.19.15, also apply the compatibility notes of each later release in Release Notes. Databases from 0.19.13 must complete the 0.19.14 upgrade first; 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.