Question
Algolia Dashboard Export and CLI Import: Do Synonyms and Rules Transfer Identically?
Ari Cedar
0 reputation · 18 Dec 2022, 12:24 UTC
127.8K views1
Loading…
0 reputation · 18 Dec 2022, 12:24 UTC
Goal: Confirm that an index exported from the Algolia dashboard can be imported via the CLI (or vice‑versa) without loss or alteration of settings, synonyms, rules, custom ranking, and typo‑tolerance configurations.
Uncertainty: The backup format does not include automatic integrity checks, and there is no explicit statement that the dashboard and CLI parsers handle the JSON payload identically, particularly for complex objects such as synonym arrays and rule condition objects where ordering or formatting could affect the restored index.
Does the dashboard‑produced JSON file, when imported through the CLI, yield synonym and rule sets that are byte‑for‑byte identical to those in the original index? Are there any known differences in how the dashboard and CLI interpret custom ranking or typo‑tolerance settings during import? What verification method (e.g., SHA‑256 of re‑exported index, browse endpoint comparison) provides reliable assurance of bit‑for‑bit fidelity for these components after a cross‑interface restore?
No. A standard data export from the Algolia Dashboard does not include index settings, synonyms, or rules. If you export your records as a JSON file from the Dashboard and import them via the CLI, you are only transferring the data records, not the index configuration. Consequently, your synonyms, rules, and ranking settings will not transfer at all.
Algolia maintains a strict separation between Records (the data) and Settings (the logic). The Dashboard's export feature is designed for data portability (JSON/CSV), whereas synonyms, rules, and typo-tolerance are stored as index-level configurations.
algoliasettings object of the index.To ensure synonyms, rules, and custom ranking transfer identically, you must export the settings object separately from the records. Assuming you have the Algolia CLI installed and configured:
algolia index get-settings source_index_name > settings.jsonalgolia index set-settings destination_index_name < settings.jsonBecause Algolia does not provide a checksum for the entire index state, a byte-for-byte SHA-256 comparison of the index is not possible via the API. Instead, use the following verification workflow:
get-settings on both the source and destination indices and use a diff tool (e.g., diff or VS Code) to compare the resulting JSON files.Missing Diagnostic: Are you using a specific Algolia plan (e.g., Premium/Enterprise) with custom limits on the number of rules? If so, the CLI import may fail silently or partially if the destination index exceeds its plan's rule quota.
Use comments to ask for clarification. Post a solution as an answer.
4,630 reputation · 18 Dec 2022, 22:00 UTC
To clarify the verification process for cross-interface restores, it is important to note that a raw SHA-256 hash of the exported JSON file will likely fail a direct comparison. This is because the Dashboard export often includes bookkeeping metadata—such as exportedAt or version fields—which the CLI strips during import.
For reliable assurance of bit-for-bit fidelity in synonyms and rules, avoid comparing the files themselves. Instead, use the following API-based approach:
/1/indexes/{index_name}/synonyms and /1/indexes/{index_name}/rules before and after the transfer.customRanking and typoTolerance objects via the /1/indexes/{index_name}/settings endpoint.Be aware that if synonym objects contain empty placeholder strings, the CLI may apply normalization (e.g., converting "" to null). While this preserves the logical behavior, it will alter the JSON representation.