Release Notes
Customer-facing changes in ApertureDB, starting with version 0.19.13. Releases are listed newest first. Links point to the current documentation; older releases may use different parameters or response formats. For deprecated features, removed syntax, and upgrade instructions, see Deprecations and migrations.
0.20.0
Image and video MIME types
-
Images and videos now store a read-only
_mime_typeproperty, matching blobs. It describes the stored content after ingestion operations and can be returned, filtered, sorted, and indexed. -
WebUI uses media MIME types for browser rendering and downloads, including the output type of requested conversions.
-
This release supports direct upgrades from 0.19.14, 0.19.15, and 0.19.16. When upgrading from 0.19.14 or 0.19.15, also apply the compatibility and upgrade notes of each later 0.19 release below. Startup fills missing MIME types for existing blobs, images and videos automatically. Referenced media and any required remote credentials must be accessible until startup completes.
-
Older binaries cannot reopen the upgraded database; retain a pre-upgrade backup for rollback.
Memory use and monitoring
-
Deprecation counters now cover planned 1.0.0 descriptor API changes, nested result selectors, removed configuration fields, and the GetStatus
cpu_utilizationfield. The Deprecations dashboard and Deprecations and migrations explain how to replace each one before upgrading. -
AddDescriptorSetandUpdateDescriptorSetaccept the 1.0.0enginesobject,ClassifyDescriptoracceptsengine,FindDescriptorandFindDescriptorBatchacceptfiltered_knnin place ofacorn, andFindDescriptorSetreturns the 1.0.0_enginesobject with"engines_format": "object". These forms are not counted as deprecated usage, so descriptor requests can be migrated before upgrading. The ACORN engine andlazy_indexing: truestill need 1.0.0. -
indexed_results_onlyis deprecated.segment_sizeandmax_segmentsare deprecated and no longer change how descriptor sets are partitioned.DiagnosticToolrequests are counted even when debug commands are disabled. -
The WebUI status page requests only the status fields it shows, so it no longer adds to
getstatus_cpu_utilization_response. -
The server no longer cancels or rejects queries because of memory use. Earlier releases aborted queries for a few seconds whenever resident memory crossed a threshold.
-
Descriptor lookup failures retain their original errors instead of appearing as missing sets. Synchronous callers receive the actual refresh outcome, and failed cleanup does not block independent index refreshes or delete set metadata prematurely.
-
Restored client session creation and refresh counters after the security migration, corrected their Grafana rate display, and removed the obsolete authentication lock contention and queue panels.
Media and query fixes
-
Descriptor searches with the L2 and IP metrics now return zero and very small vectors, which earlier releases skipped. With L2 these are often among the nearest neighbors. CS searches still skip the zero vector.
-
Blobs now store a MIME type in
_mime_type, which can be returned, filtered, sorted, and indexed without reading the blob contents. The Web UI uses this property for document previews and downloads. See FindBlob. -
AddBlobaccepts an optionalmime_typestring to set_mime_typeat ingestion and skip automatic detection, including remote prefix reads. When omitted, the server detects the type from up to the first 4096 bytes; unrecognized content usesapplication/octet-stream. See AddBlob. -
On upgrade, startup initializes missing blob MIME types before serving requests. Required blob objects and remote credentials must be accessible; completed batches survive restart. HTTPS reads now support byte ranges to retrieve content prefixes and seek within remote media.
-
Video transformations preserve audio by default.
AddVideo,FindVideo, andFindClipacceptwith_audio:falseto omit it. Applications that relied on silent transformed output should set this option explicitly. URL insertion does not accept audio removal or other transformations. -
Video operations preserve variable frame timing, accept valid inputs without container frame counts, and report metadata for the stored output. Preview size limits include audio and the finalized container.
-
FindClipapplies its requested output codec and container. Clips, intervals, previews, and frame extraction can read only the needed portion of seekable sources; performance depends on the format and source capabilities. -
Corrected fractional frame retrieval, aspect ratios after video resizing and transposition, and duration metadata when copying video streams. Byte-limited previews retain more frames when the selected or resized output fits. Raw H.264 input can be converted to MP4.
-
Requests rejected for an invalid session or insufficient permissions no longer cause other users’ concurrent writes to fail.
-
Batch requests report a retryable batch failure when the worker computing the result loses its session. Workers with valid sessions are no longer told to sign in again because of another worker’s session failure.
-
Corrected error reporting and audit records: malformed sign-in requests keep their validation errors, command errors retain actionable messages, and requests that fail before authorization are no longer recorded as access denials. Fixed a potential stall when rejecting invalid remote URLs under load.
-
Authorization timings are available separately in
graph_authorization_seconds. Graph execution breakdowns no longer count authorization time twice. See GetMetrics for the metric labels.
Security and remote media
-
User, role, and remote-credential changes now succeed or roll back together with the query’s graph changes. Backups include these settings, and clustered deployments share them across replicas. Replicas may take a short time to reflect changes. See Access Control and Remote credentials.
-
Security changes now apply to subsequent requests after they succeed. Previously, existing sessions could retain outdated permissions, and S3, Google Cloud Storage, or HTTPS reads could continue using credentials after they were changed or removed.
-
Successful sign-in is limited to
max_sessions_per_usersessions per user, default 1024. At the limit, signing in revokes the oldest session and its refresh token. Refresh replaces both tokens. User and role changes revoke affected sessions; those users must sign in again. -
Remote credentials identify an exact S3 bucket, Google Cloud Storage bucket, or HTTPS origin. After an update succeeds, subsequent reads use the new key; removal blocks reads until a credential is registered again. These rules also apply to later batch-page requests. Create or update the credential and wait for success before submitting a query that needs it. Requests already underway may finish with the previous key.
-
HTTPS media reads reuse connections. Fixed requests being refused while old idle connections were closing, even when the request limit had not been reached.
-
Rejected sessions now return
code: "unauthenticated"even when the request also encounters invalid media or an unavailable source, so clients can sign in again and retry. Internal failures now use the standard error object used for other query failures. -
Failed batch queries now release waiting page requests and allow retries. Failed inserts remove newly created media files, and active transfers can finish safely when cached remote connections are replaced.
-
Fixed internal errors for invalid media URLs or missing remote credentials, and failures when creating and removing the same user, role, or credential within one query.
-
S3 errors when checking a remote object now include the HTTP status, for example
error in HeadObject: HTTP 403 - No response body., to help distinguish denied access, missing objects, expired tokens, and wrong regions. -
Improved authentication performance under concurrent sign-in requests and bounded session and connection reuse with
max_sessions_in_cache(default 1024) andmax_remote_connections(default 32).
HTTP services and deployment
-
Community Edition no longer has a time limit. Its Docker image now uses the same server binary and configuration as the standalone image.
-
The Web UI displays the updated user and role responses, including names such as
statusandinfo. Changes to your account confirm success before asking you to sign in again, and newly added personal tokens remain available to copy from the confirmation. Browser tabs share sign-in and coordinate session renewal. Open the Web UI over HTTPS, or localhost for local use. Protected pages also open correctly from bookmarks and offer a retry when account details cannot be loaded. Temporary network failures during renewal no longer sign out every tab. -
Bounding-box previews in the Web UI update as you change coordinates and labels. Save keeps the changes; Cancel discards them. Failed saves and deletes show an error and preserve the draft, and repeated Save clicks no longer create duplicate boxes.
-
At the Properties and Details levels, the Web UI graph lists every property of a class in a scrollable list instead of the first 24. Property lists and the Data and Media tables keep their scroll positions when you change levels, pan a class out of view, or switch pages.
-
HTTP services now run independently of the native database gateway, with support for workflow WebSockets and streamed responses, including notebook sessions, Grafana Live, and streaming chat.
-
Helm and OpenTofu packages include the HTTP service without requiring an ingress controller. Workflow HTTP routes can be configured with
http.routes. -
HTTP redirects and Grafana links use the configured public port, including direct NodePort access and deployments behind an external load balancer.
-
Valid certificate replacements are loaded automatically. Existing connections can finish with the previous certificate; invalid replacements leave the last valid certificate active.
-
The certificate that Docker Compose generates is valid for
localhost,127.0.0.1,::1, and the service nameslenzandhttp-proxy, so containers on the Compose network can verify it.TLS_CERT_HOSTNAMESadds the DNS names and IP addresses your clients use. -
Fixed REST requests that could disconnect before receiving a delayed database response when the client requested connection closure.
-
Improved gateway readiness checks to wait for its listeners and required TLS certificate before accepting routed traffic.
Compatibility and upgrade notes
-
Compatible Python SDK (
aperturedbpackage) versions: 0.5.3 and 0.5.4; 0.5.4 is recommended. This release revokes sessions on upgrade, after changes to a user or its roles, including adding or removing personal tokens, and whenmax_sessions_per_useris exceeded. SDK versions before 0.5.3 run queries but do not sign in again after a revoked session: every later query on that connector fails withNot Authenticated!until a new connector is created. Versions before 0.5.0 also cannot read the schema format introduced in 0.19.15. -
SDK 0.5.3 has three remaining limitations, fixed in 0.5.4:
Operations.flipsends the numericcoderemoved in 0.19.13 (pass a flip operation withmodeinstead),Utils.create_entity_indexandUtils.create_connection_indexreturnFalsewhen the index already exists, andUtils.visualize_schemafails on a database without connection classes. -
SDK 0.5.4 descriptor helpers use the 1.0.0 request forms this release accepts:
Utils.add_descriptorsetsends theenginesobject, andDescriptors.find_similar,Images.get_similar_imagesand SPARQL searches name the descriptor set’s engine. They add no deprecated usage on this release. Earlier SDK versions count asdescriptor_set_engine_fieldanddescriptor_knn_implicit_engine. Earlier releases reject these forms, so SDK 0.5.4 requires this release or 1.0.0; use 0.5.3 with 0.19.14 to 0.19.16. -
Supported upgrades import users, roles, personal tokens, and usable remote credentials. Existing sessions and refresh tokens are not retained: sign in again after upgrading. Manage security settings through the API afterward; editing the old access-control files no longer changes access.
-
Submit Authenticate and RefreshToken as single-command queries.
-
Workers sharing a batched result must sign in as the same user. Refreshing a session or signing in again preserves that result until it expires. Access is checked for every page. See batch.
-
Update credential commands to use
originandkey. The oldname,service,resources,add_resources, andremove_resourcesselectors are no longer accepted. GetCredentials returns origin names without keys. Review imported registrations as described in Remote credentials. -
GetUsers now returns accounts under
users; GetRoles returns definitions underroles. Both responses includestatusandreturnedalongside the result object. Update clients that read names directly from the command response. This also permits accounts and roles namedstatus. -
Remove
session_cache_max_age_sec,sessions_file_refresh_rate_sec,prevent_telemetry_user_deletion, and the memory-guard fieldsresources_max_mem_limit,resources_check_mem_limit,resources_check_sleep, andresources_check_kill_timerfrom configuration; they are no longer accepted. See Configuration File for current settings. -
Startup rejects incompatible database contents. Rehearse the upgrade on a restored backup; if startup rejects the database, preserve its data and logs and contact support rather than deleting files to force it to open.
-
In Helm and OpenTofu configuration, replace
ingresshost and TLS settings withhttpsettings and remove bundled ingress-controller configuration. HTTP exposure is configured throughhttp.service;servicecontinues to configure native database exposure. Removeservice.enabledand use the desired Service type instead. Both Services are always created. UseClusterIPfor private access. Point web DNS at the new HTTP Service’s external address; the native database endpoint remains separate. -
For direct NodePort access, set fixed HTTP and HTTPS NodePorts under
http.service. Behind an external load balancer, sethttp.publicPort(Helm) orhttp.public_port(OpenTofu) to the public port, normally 443; backend NodePorts can then be allocated automatically. -
Docker Compose now uses the versioned
aperturedata/http-proxyimage. Registry mirrors must include it. ReplaceHTTP_MAX_BODY_SIZEwithHTTP_BODY_LIMITin bytes (256mbecomes268435456), and replaceHTTP_PROXY_READ_TIMEOUTwithHTTP_TIMEOUT_SECONDSin seconds. Remove upstreamNGINX_IMAGEoverrides; a full-image override now usesHTTP_PROXY_IMAGEand must provide the matching ApertureData proxy image. Use the upgrade command with--remove-orphansin the Compose guide to remove the previous HTTP service and release its published ports. -
Docker Compose deployments that use the generated certificate receive a new certificate on their first start. Clients that verify it must copy the new certificate, as described in Deploy with Docker Compose.
-
Public HTTP redirects to HTTPS when TLS is enabled. Configure API clients with the HTTPS URL directly; applications that follow redirects must preserve the request method and body for status 308.
See Deploy with Docker Compose, Deploy with Helm, and Deploy with OpenTofu for current configuration examples. Follow Changing a deployment when applying the new packages.
0.19.16
Features and improvements
-
Improved error messages for invalid constraint expressions, including operator and scalar-function arguments.
-
Fixed delays when the WebUI calculates the total size of returned blobs.
-
Fixed handling of configured memory limits larger than 32 bits and added validation to reject numeric configuration values that would overflow.
-
Published all ApertureData service images for both AMD64 and ARM64.
-
Bundled Prometheus and Loki configuration in versioned ApertureData images shared by Docker Compose, Helm, and OpenTofu deployment packages.
-
Published each Docker Compose layout in its own repository:
aperturedata/aperturedb-compose-single-node,aperturedata/aperturedb-compose-distributed-local, andaperturedata/aperturedb-compose-distributed-cloud. See Deploy with Docker Compose for package references. -
Expanded the query, response, configuration, and deployment documentation.
Compatibility and upgrade notes
-
Compatible Python SDK (
aperturedbpackage) versions: 0.5.0 to 0.5.3. Versions 0.4.56 to 0.4.61 run queries, but their schema and index helpers, such asUtils.summary,Utils.visualize_schema, andUtils.get_indexed_props, fail or report no indexes with the schema format introduced in 0.19.15. -
When upgrading Docker Compose from 0.19.15, remove upstream
PROMETHEUS_IMAGEandLOKI_IMAGEoverrides or replace them withaperturedata/prometheus:0.19.16andaperturedata/loki:0.19.16(or matching mirrored images or digests). The packages now rely on the configuration inside these images. Keeping an upstream Prometheus image silently stops ApertureDB metric collection. Update registry mirrors to include the new images. -
The database now correctly enforces configured memory limits larger than 32 bits. Check memory headroom before upgrading: the default memory guard starts aborting queries above 93% of the configured limit. Numeric configuration values that previously overflowed are now rejected.
Follow Changing a deployment when applying the new deployment packages.
0.19.15
Features and improvements
-
Added read-only access to objects at authorized HTTPS origins, with anonymous, Basic, or Bearer authentication configured through
CreateCredential. Even anonymous access requires an authorized origin. Only public HTTPS destinations are supported; redirects are not followed. -
Improved handling of large FindBlob responses. Requests that exceed the response-size limit return an error; use smaller result pages when retrieving large blobs.
-
Property names can now contain forward slashes and start with a digit, slash, or hyphen. See properties for naming rules.
-
Improved index use in queries that combine multiple filters.
-
Added Deploying ApertureDB guides for self-hosted installations using Docker Compose, Helm, and OpenTofu.
-
Docker Compose installations can configure services, resource limits, image overrides, and TLS certificates through one environment file.
-
Added the Alt+Enter shortcut for running custom queries in the WebUI.
-
Expanded query examples and consolidated migration guidance in Deprecations and migrations.
Compatibility and upgrade notes
-
Databases on 0.19.13 must first upgrade to 0.19.14, then to 0.19.15. Version 0.19.15 cannot perform the 0.19.14 database conversion.
-
GetSchema now returns property objects with
countandtype, replacing[matched, indexed, type]arrays. Read index definitions from GetIndexes, whose response usesindexesandreturnedinstead ofentitiesandconnections. Update clients that parse these fields. -
Compatible Python SDK (
aperturedbpackage) versions: 0.5.0 to 0.5.3. Versions 0.4.56 to 0.4.61 run queries, but their schema and index helpers, such asUtils.summary,Utils.visualize_schema, andUtils.get_indexed_props, fail or report no indexes with these formats.
See Database upgrades and Deprecations and migrations for the migration details, descriptor engine aliases, and checkpoint configuration changes.
0.19.14
Features and improvements
-
Added native array properties, including null elements, with membership, element-access, length, and whole-array comparisons. Array indexes can accelerate membership and selected element queries. See properties, constraints, and CreateIndex.
-
Added whole-string similarity matching and relevance-ranked full-text search with typo tolerance. See Text search expressions for the supported functions and index requirements.
-
Improved exact descriptor search performance and fixed nearest-neighbor results that could include deleted descriptors.
-
Fixed an issue with manually requested checkpoints.
-
Added deprecated-usage metrics to help identify queries that need updating.
-
Updated GetApiSchema to describe the current API.
Compatibility and upgrade notes
- Compatible Python SDK (
aperturedbpackage) versions: 0.4.56 to 0.5.3.
See Deprecations and migrations for the 0.19.14 index-command changes, request syntax migrations, and database conversion requirements.
0.19.13
Features and improvements
-
Added configurable ordered, substring, and property-type indexes, including case-sensitive and case-insensitive text options.
-
Added case-insensitive string operations to query expressions.
-
Added the transpose operation for images and videos. See operations.
-
Compatibility: See Deprecations and migrations for the media
flipoperation migration. -
Added support for AWS default credentials and Google Cloud Application Default Credentials for the database’s own storage. Credentials registered for user-supplied object URLs remain separate.
-
Improved query performance and reporting of storage write failures.
Compatibility and upgrade notes
-
Compatible Python SDK (
aperturedbpackage) versions: 0.4.56 to 0.4.61. SDK 0.5.0 and later send list-membership and date constraints and index commands in forms this release rejects. Versions before 0.4.56 do not renew sessions and fail once a session expires, with this and later releases. -
In SDK versions up to 0.5.3,
Operations.flipsends the numericcodethat this and later releases no longer accept; pass a flip operation withmodeinstead, for example{"type": "flip", "mode": "horizontal"}. -
Following the status change below,
Utils.create_entity_indexreturnsFalsewhen an identical index already exists.
The following index-command status changes from 0.19.12 can break clients that distinguish successful no-ops from errors:
-
Creating an identical normalized index definition with
CreateIndexnow returnsstatus: -1withAn identical index definition already existsininfo, instead ofstatus: 2. In 0.19.13, different parameter configurations on the same class/property can coexist; this failure applies to an identical definition after defaults are normalized. -
CreateIndexrejection of an index on a computed property now returnsstatus: -1instead ofstatus: 5. -
RemoveIndexnow rejects removal of a protected built-in index withstatus: -1; previously its removal succeeded withstatus: 0. Removing an absent ordinary index still succeeds withstatus: 0.
A duplicate-index failure rolls back graph writes in the same transaction. Do not treat that failed transaction as a completed migration. See Failures and retrying writes and the recovery guidance in CreateIndex. Inspect definitions with GetIndexes before creating missing indexes; use the request and response formats for your server version. Later releases change index identity and selectors, as described in Deprecations and migrations.
The status codes themselves have not been renumbered. These conditional-add and deletion outcomes remain unchanged: AddDescriptorSet with an existing set name and AddEntity with matching if_not_found return 2; AddConnection with if_not_found returns 2 when every source/destination pair already has a matching connection. AddConnection returns 1 for empty endpoints and 0 when it creates connections. DeleteEntity with no matches returns 0 with count: 0. See Responses and the individual command references for other outcomes.