Main Page » Getting Started » BaseX 13

BaseX 13

This article summarizes the changes that may require adjustments when migrating existing projects from BaseX 12 to BaseX 13. Please read it carefully before upgrading. All additions and updates are listed in the Changelog.

Prerequisites

BaseX 13 requires Java 21 or later (see Startup).

Databases

Compatibility

Databases created with BaseX 12 can be opened with BaseX 13, including their index structures. A database created or updated with BaseX 13 remains readable by BaseX 12 if…

  1. it has not been updated since it was created,
  2. UPDINDEX is disabled (it is now enabled by default),
  3. it was optimized with OPTIMIZE or db:optimize, or
  4. the text, attribute, token and full-text indexes are all disabled.

Otherwise, BaseX 12 rejects it. Small databases (up to 100,000 nodes) remain readable after updates: text, attribute and token indexes are restored when the database is closed, and a full-text index is rebuilt after each update as long as no node positions have shifted (see Updates). Once they have shifted, a full-text index requires OPTIMIZE ALL instead of rule 3.

BaseX 12 cannot read a database at all if…

  • Mixed content: the new FTMIXED option is enabled and a full-text index exists. Drop the index, or disable the option and optimize the database.
  • Namespaces: its namespace structure has more than 4,096 entries. Such structures are stored in a compact format.

Full-Text Index

The token normalization of the full-text index was standardized: characters that denote multiple letters are expanded (ß → ss, æ → ae, …), and missing and incorrect mappings were fixed. Full-text indexes created with older versions remain usable, but terms with affected characters are only found after the index has been rebuilt, e.g. with CREATE INDEX or OPTIMIZE ALL.

Large Inputs

In previous versions, db:create often failed with an out-of-memory error for large inputs unless ADDCACHE was enabled. Now, inputs that are too large for main memory are moved to disk while they are being added, and index structures are built within the available main memory. Large databases can be created with db:create, db:add, db:put and CREATE DB without additional configuration.

Options

  • UPDINDEX: Enabled by default: value indexes of new databases are kept up-to-date after updates. Disable it to keep updated databases readable by BaseX 12 (see Compatibility).
  • STRIPWS: Only whitespace-only text nodes are discarded; whitespace in mixed content is preserved.
  • PARALLEL: The default was raised to 32.
  • MIXUPDATES was removed: use job:execute to run updating and non-updating queries side by side.
  • LSERROR was removed: use using fuzzy N errors or the errors option of the Full-Text Functions.
  • FAIRLOCK and SPLITSIZE were removed: non-fair locking is always used, and index structures are always split based on the available main memory.
  • TAILCALLS was removed: tail calls are always eliminated.
  • ADDCACHE was removed: inputs that are too large for main memory are moved to disk while they are being added. The option must be removed from command scripts and from the options of db:create, db:add and db:put.

Server and Clients

Database Server

With the new default of HTTPLOCAL, the HTTP server no longer starts a Database Server instance. Start basexhttp with -L (see Command-Line Options) or disable the option if Clients need to connect on port 1984.

Authentication

The login handshake of the Server Protocol has been changed from digest to salted authentication, and the unsalted digest (MD5) password algorithm was removed (see User Management):

  • Clients of versions 8 to 12 can no longer connect. Third-party bindings must implement the salted handshake; the bindings in the BaseX repository have been updated.
  • Clients of Version 13 cannot connect to older servers.
  • HTTP Digest authentication was removed: the Digest value of AUTHMETHOD is no longer supported, and digest entries in AUTHALGORITHMS are ignored. Use Basic authentication via HTTPS instead. Digest authentication of the HTTP Client is still supported.
  • digest hashes in users.xml are ignored and dropped when the file is written next.
  • The client-side fallback to cram-md5 authentication and the outdated clients were removed, as well as the examples for the XML:DB API.

Web Application

  • BaseX is based on the Jetty EE10 environment. It can be deployed in any Jakarta EE 10 servlet container (Servlet 6.0 and WebSocket 2.1: Apache Tomcat 10.1, Jetty 12, WildFly 27 or later). Containers based on the javax.servlet API are not supported (see Servlet Container).
  • Static resources are served by a servlet of BaseX; the directory is specified via the path parameter. If you use a custom web.xml file, compare it with the one of the distribution.
  • Server-side forwarding (the rest:forward element and web:forward) was dropped. Use job:execute to combine multiple steps in a single request.
  • The %ws:header-param annotation was removed: use the Request Functions instead, which can now be called in WebSocket handlers.
  • WebDAV runs as a RESTXQ application. Locks are kept in main memory, and the ~webdav database is not used anymore.
  • The DBA has been redesigned.

XQuery

Language

The implementation follows the latest drafts of XQuery 4.0. Some features of BaseX 12 have been changed or dropped in the specification:

  • Record types: A record has a fixed set of fields. Optional fields (field?) and the wildcard (*) were removed, field access is strict, and subtyping is width-invariant.
  • Record declarations: Declared record types are nominative. Declarations with identical fields define distinct types.
  • Methods: The %method annotation was replaced by the =?> operator.
  • The map and array filter (e.g. [ 1, 2, 3 ]?[. != 2]) was removed.
  • Casting: Casting from strings follows XSD 1.1; casts to xs:anyURI never fail.
  • The nondeterministic prefix for dynamic function calls was removed: calls of functions that are statically unknown are treated as nondeterministic (see XQuery Extensions).

Functions

The following functions were renamed or removed:

Description BaseX 13 BaseX 12
Insert separator between items fn:insert-separator fn:sequence-join, fn:intersperse
Return function identity removed fn:function-identity
Return key-value pairs of a map map:entries (singleton maps) map:pairs
Build map from key-value pairs map:build map:of-pairs
Return keys of matching entries map:keys, map:filter map:keys-where
Functions: Higher-order functions removed Higher-Order Functions Module
Return intermediate results of a fold fn:scan (results wrapped in arrays) hof:scan-left
Fold non-empty sequence without seed fn:fold-left hof:fold-left1
Return greatest items fn:sort-by, fn:sort-with hof:top-k-by, hof:top-k-with
Pad string fn:pad-string string:format
Convert between strings and binary data Binary Functions convert:binary-to-string, convert:string-to-base64, convert:string-to-hex
Forward request removed web:forward

The following changes may affect existing code:

Serialization

  • The default of html-version changed from 4.0 to 5.0.
  • With html-version and version, control characters that the requested version does not allow raise an error.
  • The custom parameters indents, newline and tabulator are superseded by the standard parameters indent-unit and line-ending.

See Serialization for more details.

Graphical User Interface

Only a single GUI instance is opened per project directory, and the fullscreen mode was removed (see Graphical User Interface).

⚡Generated with XQuery
 
BaseX 13