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. See :ref:`deprecations` for removed inputs and their replacements in 1.0.0. .. _release-candidate: .. _release-1-0-0: 1.0.0 ----- SDK compatibility +++++++++++++++++ * Python SDK (``aperturedb``) **1.0.2** supports servers 0.20.0 and 1.0.0 over native TCP/TLS and HTTP. Applications using SDK 0.5.x must upgrade the SDK before upgrading the server to 1.0.0. Raw queries must use the command syntax of the connected server. * On server 1.0.0, the SDK reads grouped connection selectors in schema and index results and supplies them when creating connection indexes. Typed connection CSVs select the endpoint objects before adding their connection. See :doc:`parameters/class`, :doc:`commands/GetSchema`, and :doc:`commands/GetIndexes`. * SDK helpers and CSV/model loaders support descriptor classes and vector indexes. See :doc:`DescriptorIndexes`. Query protocol and connections ++++++++++++++++++++++++++++++ * Native requests send a JSON-string session token, the JSON command array, a network-endian blob count, and sized binary blobs. * HTTP queries use ``/api/``. Multipart responses carry JSON metadata followed by raw binary blobs. See :doc:`QueryProtocol` for framing, completion checks, and retry guidance. * Deferred media cancellation and unexpected response failures close the connection and release its accepted session. Subsequent connections remain available after either standard or non-standard exceptions. * Queued and active deferred media work no longer consumes the network send deadline. Blocked socket writes retain their 600-second timeout. * Accepted connections no longer reserve a query thread. Configure networking and execution independently with ``network_threads``, ``query_threads``, ``query_queue_bytes_mb``, and ``max_read_transactions``. Lenz opens backend connections on demand. Expressions +++++++++++ * Added scalar type checks: ``is_number``, ``is_bool``, ``is_str``, and ``is_date``. They return false for null or missing values. * Added explicit conversions: ``str_to_number``, ``number_to_str``, ``str_to_bool``, ``bool_to_str``, ``bool_to_number``, ``number_to_bool``, ``str_to_date``, and ``date_to_str``. They enforce the source type and return null for null or missing inputs. * Added ``if`` to select between two values using a boolean condition. It evaluates only the selected branch and returns null for a null or missing condition. See :doc:`parameters/constraints`. Descriptor indexing +++++++++++++++++++ * Flat, IVF, HNSW, and ACORN indexes now commit or roll back with graph changes in the same transaction. Queries see their own pending descriptor changes. * A bounded memory cache accelerates descriptor search and eligible HNSW append batches in both synchronous and lazy modes. Configure its budget with ``descriptor_index_cache_size_mb`` (default 512; zero disables caching). Searches continue while the cache rebuilds, and indexes larger than the budget remain searchable. See :doc:`ConfigFile`. * Descriptor sets are replaced by descriptor classes and vector indexes on their binary column. Each index has one kind (``flat``, ``ivf``, ``hnsw``, or ``acorn``) with engine settings directly in ``params``. Manage vector indexes with ``CreateIndex``, ``UpdateIndex``, ``GetIndexes``, and ``RemoveIndex``. See :doc:`DescriptorIndexes`. * Class scope always applies before descriptor top-k. Classless search merges compatible indexes into one global top-k and rejects incompatible definitions. * ``GetIndexes`` reports indexed and pending descriptor counts and training state. * The ACORN engine supports filtered vector search. HNSW ``filtered_knn`` uses exact search for small eligible subsets. Configure index builds and lazy indexing through :doc:`commands/UpdateIndex`. Classes, schema, and query results ++++++++++++++++++++++++++++++++++ * All object types require an explicit class on insertion and accept ``with_class`` on reads and mutations. Classes are scoped by object type; connection classes are scoped by both endpoint classes and object types. :doc:`commands/AddConnection` and :ref:`connect` take the connection name as a string in ``class``. The objects being connected supply the endpoint classes and types. Connection filters group class names in ``class`` (``src``, ``connection``, ``dst``) and endpoint types in ``target`` (``src``, ``dst``). :doc:`commands/FindConnection` takes the class and type of each referenced endpoint from its selected objects. Schema edges, connection index definitions, and aggregate definitions return the same selector. ``RenameClass`` preserves object identities; ``RemoveClass`` removes empty classes. See :doc:`parameters/class`. * ``GetSchema`` returns typed arrays of object and connection classes. Clients upgrading from 0.20.0 can find the response fields in :doc:`commands/GetSchema`. * Owner parameters in both directions support source grouping and per-group pagination. Projected rows include read-only class fields; connections also include endpoint type and class fields. * Media results remain available across commands in the same request. Failed commands discard partial output blobs while preserving successful results. * :doc:`commands/AddBlob` now recognizes HTML, XML, SVG, vCard, iCalendar, and WebVTT from their content signatures. An explicit ``mime_type`` still takes precedence. Connection aggregates +++++++++++++++++++++ :doc:`commands/CreateAggregate` maintains a read-only property on each parent, such as an order total calculated from its line items. Each matching outgoing connection contributes once. The aggregate can count, sum, average, or take the minimum or maximum of values from the connections or their destination objects. Supply ``src_property``, ``operation``, and either ``dst_expression`` or ``connection_expression`` directly in the command body. Creation includes existing connections. Later changes to connections or input properties update the parent and any dependent aggregates in the same transaction. Use :doc:`commands/GetAggregates` to list definitions and :doc:`commands/RemoveAggregate` to remove a definition and clear its stored values. Compatibility and upgrade notes +++++++++++++++++++++++++++++++ Version 1.0.0 upgrades databases from 0.20.0 only. Before upgrading, start each database with 0.20.0 and wait until it answers queries, for example ``GetStatus``; its startup conversions are then complete. 1.0.0 refuses to open databases from older releases, or databases whose 0.20.0 startup has not completed, and leaves them unchanged. Upgrade those through 0.20.0 first; 1.0.0 does not include its conversions. The query and health ports now accept connections only after startup checks and migrations complete, so TCP readiness probes no longer pass while startup is still converting an existing database. When a clustered server restarts at the same address, it waits up to two negotiated ZooKeeper session timeouts for its previous discovery registration to expire. If another session still owns the address, startup fails and the other registration stays intact. Check for another replica configured with the same role, host, and port before retrying. Deploy matching server, checkpoint and administration binaries together. Checkpoint publication waits until the completed snapshot uses the current logical graph format. If an upgrade cannot complete, the previous recovery point is preserved so that 0.20.0 can still open it. Upgrade preflight checks continue to reject unsupported legacy schemas. Existing descriptor sets become descriptor classes. Supported custom properties move losslessly into vector-index metadata. Unsupported data or customer connections to set nodes prevent conversion. Keep a pre-upgrade backup for rollback. Some descriptor IDs and split customer-connection IDs change. Conversion repairs internal graph references. Refresh references held outside the graph or stored as ordinary string properties after conversion. Interrupted upgrades resume on restart before serving requests. Released IVF settings with ``nprobe`` greater than ``nlist`` are normalized to the resolved list count during migration, preserving FAISS's full-list probing behavior. An omitted or zero list count uses the new default of 100. New API requests instead reject excessive probe counts, unknown IVF or HNSW parameter names, and invalid parameter types or ranges before writing graph data. Migration removes previously ignored engine parameters. Migrated engines remain synchronous; enable lazy indexing explicitly after upgrading. .. _deprecations: Removed APIs and replacements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 32 68 * - Earlier API or configuration - Changes for 1.0.0 * - Descriptor-set commands, their system properties, and the ``set`` parameter - Use descriptor classes. Specify ``class`` on insertion and ``with_class`` on selection. Use ``CreateIndex``, ``UpdateIndex``, ``GetIndexes``, and ``RemoveIndex`` for vector indexes. Put engine settings in ``params`` and custom set properties in ``metadata``. KNN and classification require an explicit ``engine``. See :doc:`DescriptorIndexes`. * - Implicit node and connection classes - All node Add commands require an application class scoped by node type. Supply a class for each customer connection. Its scope includes the classes and object types of both endpoints. See :doc:`parameters/class`. * - Previous schema and index response formats - Use ``scope`` values ``node``, ``edge``, or ``all`` with :doc:`commands/GetSchema`. Read its flat ``nodes`` and ``edges`` arrays. Ownership links are excluded from schema edges. :doc:`commands/GetIndexes` returns a flat array of complete typed definitions. Indexes have no graph identity or connections. * - Cached-result paging with ``batch``, ``batch_time_to_live``, and ``batch_cleaner_interval`` - Use ordinary result selection and pagination. ``FindDescriptorBatch`` remains available for multi-vector nearest-neighbor searches. * - ``max_simultaneous_clients`` - Configure query workers with ``query_threads`` and networking with ``network_threads``. See `Query protocol and connections`_. * - Property-keyed constraints and object-form groups - Use array expressions in ``constraints``, connection filters, and ``if_not_found``. Replace ``{"age": [">=", 18]}`` with ``["$age", ">=", 18]``. * - ``sort``, ``limit``, ``group_by_source``, and ``uniqueids`` inside ``results`` - Place these parameters at the command level. * - ``index_type`` and ``property_key`` - Use ``target`` and ``property``. ``CreateIndex`` and ``RemoveIndex`` also require ``kind``. * - ``FaissFlat``, ``FaissIVFFlat``, and ``FaissHNSWFlat`` - Use ``Flat``, ``IVF``, and ``HNSW``, respectively. * - ``DiagnosticTool`` - Use the documented administration interfaces or contact support for database repair procedures. * - Comments in JSON requests and configuration files - Remove comments before sending requests or loading configuration files. * - ``GetStatus.cpu_utilization`` - Use host or container CPU monitoring. The old field always returned zero. * - ``enable_dfs`` - Select storage with ``storage_type``, ``storage_bucket_name``, and ``storage_credentials``. See :doc:`ConfigFile`. * - ``collect_thread_interval``, ``collect_interval_set``, and ``sys_status_periodic_log`` - Remove these unused fields from configuration files. .. _release-0-20-0: 0.20.0 ------ SDK compatibility +++++++++++++++++ * Compatible Python SDK (``aperturedb`` package) versions are **1.0.2**, **0.5.4**, and **0.5.3**. SDK 1.0.2 supports both native TCP/TLS and HTTP on this server. See :ref:`release-1-0-0` for client upgrade considerations. For applications staying on the 0.5 series, use 0.5.4. * This release revokes sessions on upgrade, after changes to a user or its roles, including adding or removing personal tokens, and when ``max_sessions_per_user`` is 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 with ``Not 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.flip`` sends the numeric ``code`` removed in 0.19.13 (pass a flip operation with ``mode`` instead), ``Utils.create_entity_index`` and ``Utils.create_connection_index`` return ``False`` when the index already exists, and ``Utils.visualize_schema`` fails on a database without connection classes. * SDK 0.5.4 descriptor helpers use the new engine syntax accepted in 0.20.0: ``Utils.add_descriptorset`` sends the ``engines`` object, and ``Descriptors.find_similar``, ``Images.get_similar_images`` and SPARQL searches name the descriptor set's engine. They add no deprecated usage on this release. Earlier server releases reject these forms; use SDK 0.5.3 with 0.19.14 to 0.19.16. Media MIME types ++++++++++++++++ * Blobs, images, and videos now store a read-only ``_mime_type`` property. It describes the stored content after ingestion operations and can be returned, filtered, sorted, and indexed without reading the media contents. * ``AddBlob`` accepts an optional ``mime_type`` string to set ``_mime_type`` at 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 uses ``application/octet-stream``. See :doc:`commands/AddBlob`. * The Web UI uses media MIME types for previews and downloads, including the output type of requested conversions. Deprecations and API updates ++++++++++++++++++++++++++++ Deprecation counters cover descriptor API usage, nested result selectors, deprecated configuration fields, and ``GetStatus.cpu_utilization``. The Deprecations dashboard shows usage. See :ref:`deprecations` for the replacements in 1.0.0. .. list-table:: :header-rows: 1 :widths: 32 68 * - API or parameter - Behavior in 0.20.0 * - ``AddDescriptorSet`` and ``UpdateDescriptorSet`` - Accept the ``engines`` object without counting deprecated usage. * - ``ClassifyDescriptor`` - Accepts ``engine`` without counting deprecated usage. * - ``FindDescriptor`` and ``FindDescriptorBatch`` - Accept ``filtered_knn`` in place of ``acorn`` without counting deprecated usage. * - ``FindDescriptorSet`` - Returns an ``_engines`` object with ``"engines_format": "object"``. This form does not count as deprecated usage. * - ``indexed_results_only`` - Deprecated in this release. * - ``segment_size`` and ``max_segments`` - Deprecated. Descriptor-set partitioning ignores both values. * - ``DiagnosticTool`` - Requests increment the deprecation counter even when debug commands are disabled. Memory use and monitoring +++++++++++++++++++++++++ * 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. Failed index cleanup no longer blocks other index refreshes or removes set metadata prematurely. * Restored client session creation and refresh counters and corrected their Grafana rate display. 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. * Video transformations preserve audio by default. ``AddVideo``, ``FindVideo``, and ``FindClip`` accept ``with_audio:false`` to 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. * ``FindClip`` applies 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. * HTTPS reads now support byte ranges to retrieve content prefixes and seek within remote media. * 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 :doc:`commands/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 :doc:`AccessControl` and :doc:`RemoteCredentials`. * 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_user`` sessions 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) and ``max_remote_connections`` (default 32). HTTP services and deployment ++++++++++++++++++++++++++++ * Community Edition no longer has a time limit. * Web UI tabs share sign-in and coordinate session renewal. Temporary network failures during renewal no longer sign out every tab. Account changes confirm success before requesting a new sign-in, and newly created personal tokens remain available to copy. Open the Web UI over HTTPS, or localhost for local use. * Protected Web UI pages open correctly from bookmarks and offer a retry when account details cannot be loaded. * Bounding-box previews in the Web UI update as you change coordinates and labels. Failed saves and deletes preserve the draft and show an error; repeated Save clicks no longer create duplicate boxes. * The Web UI graph displays all class properties in a scrollable list. Property lists and the Data and Media tables preserve their scroll positions while navigating. * 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``. * Each ZooKeeper server can set CPU and memory requests and limits through ``zookeeper.resources``. Each workload can also configure its own pod tolerations. See the examples in :doc:`deployment/Helm` and :doc:`deployment/OpenTofu`. * Helm and OpenTofu now publish ZooKeeper peer DNS records before pod readiness by default, so peers can discover each other during startup. Both packages and distributed :doc:`Docker Compose ` also let a stalled ZooKeeper leader retry election when a voter is looking for a leader and a quorum has yet to respond. The default threshold is 30 seconds. * Helm and OpenTofu configure CPU and memory requests and limits independently for Grafana, Loki, Prometheus and each database pod's Promtail. The HTTP proxy now defaults to a CPU limit of one core. * When upgrading a deployment that supplies the Grafana admin password inline, move it from ``telemetry.grafana.adminPassword`` to ``telemetry.adminPassword`` in Helm or from ``telemetry.grafana.admin_password`` to ``telemetry.admin_password`` in OpenTofu. For an existing Kubernetes Secret, move its name from ``telemetry.grafana.existingSecret`` to ``telemetry.adminPasswordSecret`` in Helm or from ``telemetry.grafana.existing_secret`` to ``telemetry.admin_password_secret`` in OpenTofu. * Move the monitoring bearer credential out of ``telemetry.auth``. In Helm, use ``telemetry.authPassword`` for the inline value or ``telemetry.authPasswordSecret`` for the name of an existing Secret. The OpenTofu keys are ``telemetry.auth_password`` and ``telemetry.auth_password_secret``. * The monitoring PVC now uses the global storage class. Move ``telemetry.persistence.storageClass`` to ``global.storageClass`` in Helm or ``telemetry.persistence.storage_class`` to ``global.storage_class`` in OpenTofu. An empty value uses the cluster default. When upgrading, keep the storage class of the existing monitoring claim. * Helm's ``dbEphemeralVolume`` and OpenTofu's ``db_ephemeral_volume`` can place database and checkpointer scratch data on per-pod generic ephemeral claims. Database pods mount the claim at ``/aperturedb/db`` and checkpointer pods at ``/checkpointer/db``. One setting controls capacity and storage class for both pod types. The default uses each container's filesystem. * Lenz concurrency can be set independently through ``lenz.adbMaxConcurrency`` (Helm) or ``lenz.adb_max_concurrency`` (OpenTofu). Omitted values keep the existing database-derived default. * Compose has optional per-service CPU and memory overrides with unlimited defaults. The deployment guides list every override, and separate LoadBalancer, NodePort, and ClusterIP endpoint discovery instructions. * Removed the OpenTofu module's historical ``moved.tf`` state migration. * 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 names ``lenz`` and ``http-proxy``, so containers on the Compose network can verify it. ``TLS_CERT_HOSTNAMES`` adds 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 +++++++++++++++++++++++++++++++ * 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 before serving requests. Referenced media and any required remote credentials must remain accessible until startup completes. Interrupted upgrades resume on restart. Older binaries cannot reopen the upgraded database; retain a pre-upgrade backup for rollback. * 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. * Update credential commands to use ``origin`` and ``key``. The old ``name``, ``service``, ``resources``, ``add_resources``, and ``remove_resources`` selectors are no longer accepted. ``GetCredentials`` returns origin names without keys. Each bucket or HTTPS origin is imported separately. Entries with paths, trailing slashes or malformed keys are skipped and logged. For overlapping origins, the first structurally valid key in credential-name order is retained. Review origins with ``GetCredentials``, replace keys with ``UpdateCredential`` and test a media read. See :doc:`RemoteCredentials` for credential management. * ``GetUsers`` now returns accounts under ``users``; ``GetRoles`` returns definitions under ``roles``. Both responses include ``status`` and ``returned`` alongside the result object. Update clients that read names directly from the command response. * Remove ``session_cache_max_age_sec``, ``sessions_file_refresh_rate_sec``, ``prevent_telemetry_user_deletion``, and the memory-guard fields ``resources_max_mem_limit``, ``resources_check_mem_limit``, ``resources_check_sleep``, and ``resources_check_kill_timer`` from configuration; they are no longer accepted. See :doc:`ConfigFile` 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 ``ingress`` host and TLS settings with ``http`` settings and remove bundled ingress-controller configuration. HTTP exposure is configured through ``http.service``; ``service`` continues to configure native database exposure. Remove ``service.enabled`` and use the desired Service type instead. Both Services are always created. Use ``ClusterIP`` for 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, set ``http.publicPort`` (Helm) or ``http.public_port`` (OpenTofu) to the public port, normally 443; backend NodePorts can then be allocated automatically. * Docker Compose now uses the versioned ``aperturedata/http-proxy`` image. Registry mirrors must include it. Replace ``HTTP_MAX_BODY_SIZE`` with ``HTTP_BODY_LIMIT`` in bytes (``256m`` becomes ``268435456``), and replace ``HTTP_PROXY_READ_TIMEOUT`` with ``HTTP_TIMEOUT_SECONDS`` in seconds. Remove upstream ``NGINX_IMAGE`` overrides; a full-image override now uses ``HTTP_PROXY_IMAGE`` and must provide the matching ApertureData proxy image. Use the upgrade command with ``--remove-orphans`` in 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 :doc:`deployment/DockerCompose`. * 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 :doc:`deployment/DockerCompose`, :doc:`deployment/Helm`, and :doc:`deployment/OpenTofu` for current configuration examples. Follow :ref:`deployment-upgrades` when applying the new packages. .. _release-0-19-16: 0.19.16 ------- SDK compatibility +++++++++++++++++ * Compatible Python SDK (``aperturedb`` package) 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 as ``Utils.summary``, ``Utils.visualize_schema``, and ``Utils.get_indexed_props``, fail or report no indexes with the schema format introduced in 0.19.15. Features and improvements +++++++++++++++++++++++++ * Improved error messages for invalid constraint expressions, including operator and scalar-function arguments. * Fixed delays when the Web UI 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``, and ``aperturedata/aperturedb-compose-distributed-cloud``. See :doc:`deployment/DockerCompose` for package references. Compatibility and upgrade notes +++++++++++++++++++++++++++++++ * When upgrading Docker Compose from 0.19.15, remove upstream ``PROMETHEUS_IMAGE`` and ``LOKI_IMAGE`` overrides or replace them with ``aperturedata/prometheus:0.19.16`` and ``aperturedata/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 :ref:`deployment-upgrades` when applying the new deployment packages. .. _release-0-19-15: 0.19.15 ------- SDK compatibility +++++++++++++++++ * Compatible Python SDK (``aperturedb`` package) 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 as ``Utils.summary``, ``Utils.visualize_schema``, and ``Utils.get_indexed_props``, fail or report no indexes with the schema and index response formats introduced in this release. 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 :doc:`commands/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 :doc:`parameters/properties` for naming rules. * Improved index use in queries that combine multiple filters. * Added :doc:`Deployment` 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 Web UI. 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. * :doc:`commands/GetSchema` now returns property objects with ``count`` and ``type``, replacing ``[matched, indexed, type]`` arrays. Read index definitions from :doc:`commands/GetIndexes`, whose response uses ``indexes`` and ``returned`` instead of ``entities`` and ``connections``. Update clients that parse these fields. * Replace ``commits_between_checkpoints`` with ``seconds_between_checkpoints``. Scheduled checkpoints run when there are pending changes. .. _release-0-19-14: 0.19.14 ------- SDK compatibility +++++++++++++++++ * Compatible Python SDK (``aperturedb`` package) versions: 0.4.56 to 0.5.3. 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 :doc:`parameters/properties`, :doc:`parameters/constraints`, and :doc:`commands/CreateIndex`. * Added whole-string similarity matching and relevance-ranked full-text search with typo tolerance. See :ref:`text-search` 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 :doc:`commands/GetApiSchema` to describe the current API. Compatibility and upgrade notes +++++++++++++++++++++++++++++++ * On the first startup with a 0.19.13 database, the 0.19.14 server or checkpointer converts stored JSON properties on objects and connections according to their top-level value. * Objects remain ``Json`` properties with their nested content intact. * Arrays become native ``Array`` properties. Nulls, booleans, strings, and numbers keep their positions. Each immediate object or array becomes a string containing its original JSON text, including whitespace, escapes, and number spellings. For example, reading the migrated property ``[1,{"x":2},[3,4]]`` returns the following array. .. code-block:: json [1,"{\"x\":2}","[3,4]"] A client that needs the nested object or array can decode the corresponding string with a JSON parser. * Booleans, strings, and numbers become native scalar properties. An integer converted to a native number must be exactly representable. For example, ``[9007199254740993,{}]`` stops the upgrade, while ``[[9007199254740993]]`` becomes ``["[9007199254740993]"]``. A top-level ``null``, malformed JSON, or a value that exceeds a native storage limit also stops the upgrade. Top-level strings have a limit of 65,535 bytes. The conversion rolls back properties, schema counts, and indexes together. Use the reported object or connection ID and property name to correct the value on 0.19.13, then retry. * Back up the database before upgrading. In a cluster, also back up the corresponding cluster state and stop all 0.19.13 servers and checkpointers before starting 0.19.14. The server replays committed changes into a private checkpoint copy before converting and publishing it. Downgrading requires restoring the pre-upgrade backup. * Replace index type options ``bool``, ``number``, ``date``, and ``text: false`` with ``"kind": "ordered"`` for scalar indexing. Ordered indexes cover all supported scalar types. See :doc:`commands/CreateIndex` for other kinds. * Indexes no longer return an ``index_id``. Identify an index by target, class, property, and kind. ``CreateIndex`` returns a success status; inspect definitions with :doc:`commands/GetIndexes`. Remove and recreate an index to change its parameters. .. _release-0-19-13: 0.19.13 ------- SDK compatibility +++++++++++++++++ * Compatible Python SDK (``aperturedb`` package) 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. * In SDK versions up to 0.5.3, ``Operations.flip`` sends the numeric ``code`` that this release no longer accepts; pass a flip operation with ``mode`` instead, for example ``{"type": "flip", "mode": "horizontal"}``. * ``Utils.create_entity_index`` returns ``False`` when ``CreateIndex`` rejects an identical existing index. 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 :doc:`parameters/operations`. * The media ``flip`` operation now uses ``mode`` with ``horizontal``, ``vertical``, or ``both`` instead of numeric ``code``. See :doc:`parameters/operations`. * 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 +++++++++++++++++++++++++++++++ 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 ``CreateIndex`` now returns ``status: -1`` with ``An identical index definition already exists`` in ``info``, instead of ``status: 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. * ``CreateIndex`` rejection of an index on a computed property now returns ``status: -1`` instead of ``status: 5``. * ``RemoveIndex`` now rejects removal of a protected built-in index with ``status: -1``; previously its removal succeeded with ``status: 0``. Removing an absent ordinary index still succeeds with ``status: 0``. A duplicate-index failure rolls back graph writes in the same transaction. Do not treat that failed transaction as a completed migration. See :ref:`response-error-phases` and the recovery guidance in :doc:`commands/CreateIndex`. Inspect definitions with :doc:`commands/GetIndexes` before creating missing indexes; use the request and response formats for your server version.