Search the DataSaudi catalog of 277 statistical cubes.

Returns an ENVELOPE (not a bare list): {query, scope, total_matches, returned, catalog_size (277), complete, results, note}. results holds compact {name, caption, domain} hits. total_matches is the TRUE number of matching cubes; when complete is true, results contains ALL of them - there is no hidden cap. Never infer a result ceiling from len(results): read total_matches and complete. When complete is false the result is a page - refine the query or pass offset (the next start index, from the note) to page through the rest.

scope: 'catalog' (title/topic), 'measures' (measure names), or 'levels' (drillable level names - NOT member values; 'members' is an alias). locale='ar' also matches the Arabic catalog annotations (topic/subtopic/source); cube names/captions themselves are English only. An empty query returns a labeled preview (first 25 of 277). A space-separated query that finds nothing is retried once with spaces replaced by underscores.

Introspect one cube: its drillable level names and measures. Pass level to also list that level's members. locale ('en' or 'ar') controls the language of the returned member captions (e.g. locale='ar' -> 'الرياض' instead of 'Al-Riyadh'); the level/measure NAMES stay as-is since query_cube matches them literally. Unknown cube -> error with 'did you mean'.

Query a cube by drilldowns (level names) + measures; returns a compact, paginated result with the resolved query echoed back.

cut filters by member: a {level: member_id} mapping, e.g. {"Province": "1"} to keep only that province. Use the member ID (from describe_cube(cube, level=...)), NOT its caption. locale ('en' or 'ar') sets the language of member captions in the result rows (e.g. 'الرياض' vs 'Al-Riyadh'); member IDs and numbers are unaffected. Validates level/measure names AND cut level names locally and fails loud with the valid options.

limit: max rows per call (default 100), HARD-CAPPED at 5000. A larger value is silently reduced to 5000 - the tool will NOT return an unbounded result, because a single result over ~1MB is rejected outright by the client (no partial data comes back). THERE IS NO 'get everything in one call'. To get more than one page, do NOT raise limit: page with offset (the note gives you the next offset; repeat until complete), OR narrow with a cut / fewer drilldowns. Paging or narrowing is the intended path and is faster than one giant call that errors. offset: start row of this page (default 0). When combining pages, only sum additive measures (counts/sums); never average an index or ratio across pages.

Note: a cut on a valid level but nonexistent member returns 0 rows (reported as 'valid query, no matching data'), not an error - check the member id if you expected rows.