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 |
| 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. |
| Use |
Omitting | Specify |
| Use the engines object, with lowercase |
| Name a configured engine with |
| Use |
| 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. |
| Remove them. They are accepted without effect and no longer change how descriptors are partitioned. |
Descriptor engines | Use |
| 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. |
| Select storage with |
| 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 |
|---|---|
| Accepted configuration fields with no active collection behavior. |
| Accepted but does not enable periodic status logging. |
| 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 |
|---|---|
| Property-keyed constraint objects, including conditional and nested filters and object-form groups. |
| Sorting specified inside |
| These selectors explicitly supplied inside |
| JSON parsed with comments. |
| Index commands using the old selector names. |
| Index creation or removal without an explicit |
| Resolutions of |
| Resolutions of |
| Resolutions of |
| Requests for |
|
|
| Descriptor-set commands supplying |
| Creating a descriptor set with an omitted or empty engine selection and no |
|
|
|
|
| Requests supplying these removed parameters, including false values. Replace |
| Descriptor-set commands supplying these ignored fields. Remove them. |
| Explicit requests for |
| Responses actually emitting |
| Configuration-file loads containing |
| 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 |
Named remote credentials (0.20.0) | Identify credentials by |
| Remove these configuration fields; they are rejected. See Configuration File for current session settings. |
| 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. |
| Read an object containing |
| Read |
| Use |
Index type options | Use |
Index identifiers returned as | Identify an index by target, class, property, and kind. |
Numeric | Use |
| Use |
| Use |
| These configuration fields are rejected. Configure |
Helm | Select the chart version. Published charts pin the database and Web UI images together. |
OpenTofu | Select the module package tag. These inputs are not available; the |
| Use |
Tools image | Use |
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
-
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.
-
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.
-
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.
-
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.