Read an Aria Full-Text Index Safely with aria_ftdump

When search results look thin and you suspect the full-text index rather than the query, aria_ftdump lets you look straight at that index. You will pick the correct key number and request word, length or global statistics from it. The examples match the aria_ftdump installed here from MariaDB 10.11.14-0ubuntu0.24.04.1.

Allow about fifteen minutes. You need shell access to the host containing the table's Aria files and the MariaDB utilities package. This guide reads index files only. It does not repair, rebuild, optimise or delete a table.

Safety boundary: Inspect a copy when possible. Do not run diagnostic tools against a table while MariaDB is writing it unless your maintenance procedure explicitly makes that safe. Never use this command as a substitute for a backup.

1. Confirm the installed command

Start with the command path, package version and built-in help. These are ordinary read-only checks and do not require elevated privileges:

$ command -v aria_ftdump
/usr/bin/aria_ftdump
$ dpkg-query -W -f='${Package} ${Version}\n' mariadb-server
mariadb-server 1:10.11.14-0ubuntu0.24.04.1
$ aria_ftdump --help
Use: aria_ft_dump <table_name> <index_num>
  -c, --count         Calculate per-word stats (counts and global weights).
  -d, --dump          Dump index (incl. data offsets and word weights).
  -l, --length        Report length distribution.
  -s, --stats         Report global stats.

The help output calls the program aria_ft_dump in its usage line, but the installed executable is aria_ftdump. Use the executable name shown by command -v. This package reports no useful --version option, so record the package version instead.

2. Locate the table files

An Aria table normally has a .MAI index file and a .MAD data file. First identify the exact table and check that its index file is readable:

$ TABLE_DIR='/var/lib/mysql/example'
$ TABLE_NAME='documents'
$ ls -l "$TABLE_DIR/$TABLE_NAME.MAI" "$TABLE_DIR/$TABLE_NAME.MAD"
$ test -r "$TABLE_DIR/$TABLE_NAME.MAI" && echo 'index file is readable'

Replace both placeholder values with the directory and base name from your installation. Keep TABLE_NAME free of the .MAI suffix for the first aria_ftdump invocation. If the files are under a protected database directory, read access may require an administrator or a carefully scoped sudo command. Do not make the files world-readable just to run a report.

Checkpoint: If either file is missing, stop here. A guessed path or a different table can produce a report that looks plausible but answers the wrong question.

3. Find the full-text key number

aria_ftdump takes an index number, not a key name. Ask aria_chk to describe the table:

$ aria_chk --description "$TABLE_DIR/$TABLE_NAME.MAI"
Aria file:           /var/lib/mysql/example/documents.MAI
Table description:
Key Start Len Index    Type
1   ...                  unique
2   ...                  fulltext varchar2 packed

Your offsets, lengths and keys will differ. Use the number in the Key column for the row whose Index value is fulltext. In this illustrative output that number is 2. Do not assume that the full-text key is always the first key.

aria_chk has checking and repair modes as well. Do not add --check, --recover or repair options to this discovery step: those are separate operations with different safety implications.

4. Request one report

Run aria_ftdump with the table base path, the full-text key number and one report option. The command is normally unprivileged when the files are readable:

$ aria_ftdump "$TABLE_DIR/$TABLE_NAME" 2 --stats
Total words: 123
Unique words: 27
Longest word: 11 chars (database)
Median length: 6
Most common word: 8 times, weight: 0.421000 (search)

The figures above are representative placeholders, not expected values for your table. The --stats report describes the index globally. Verify success with the shell status immediately afterwards:

$ printf 'aria_ftdump status: %s\n' "$?"
aria_ftdump status: 0

Use the other report modes when their detail is what you need:

Dump output can be large. Save it to a new file only after choosing a destination that does not overwrite evidence or an existing report:

$ OUT='/tmp/documents-fulltext.dump'
$ aria_ftdump "$TABLE_DIR/$TABLE_NAME" 2 --dump > "$OUT"
$ test -s "$OUT" && wc -l "$OUT"

Redirection creates or truncates $OUT. If that path already matters, choose another name or make a backup first. A failed command can leave a partial output file; remove that temporary file only after checking that it is not needed.

5. Read failures without guessing

got error 132 means MariaDB reported an old database file. It is not evidence that the full-text index is empty. Check that you selected the correct Aria table, that the utility and server packages are compatible, and that the table was closed cleanly before retrying. Preserve the original files while investigating.

An error about opening the table usually points to a path or permission problem. Recheck the exact files without changing them:

$ realpath "$TABLE_DIR/$TABLE_NAME.MAI"
$ stat "$TABLE_DIR/$TABLE_NAME.MAI" "$TABLE_DIR/$TABLE_NAME.MAD"
$ test -r "$TABLE_DIR/$TABLE_NAME.MAI" && echo readable

If the command reports a missing or invalid index, rerun aria_chk --description and compare the key number with the full-text row. Do not try successive numbers against a live table and treat the first output as authoritative.

None of the examples changes MariaDB configuration or table contents. The only state-changing risk shown is shell redirection to an existing report path. Recover by using the original backup or by removing only a confirmed disposable partial report.

Done means