Validate¶

Commands for checking model quality — locally, against a live model, and in CI. See Output & scripting for the CI-specific flags.

bpa — Best Practice Analyzer¶

tx bpa run [model] [options]
tx bpa rules <subcommand>

bpa run evaluates the model against a rule collection and reports findings by severity; --fix applies auto-fixes where the rule provides one (FixExpression).

Besides property assignments (IsHidden = true) and Delete(), a fix expression can rewrite the object's DAX:

Only the flagged references change; formatting and comments are kept. A reference the rewrite cannot resolve for certain leaves the expression untouched and is reported under fix errors instead. For example, a column name that exists in more than one table, a name that also appears as a string literal (a column the expression builds with ADDCOLUMNS), or a measure qualified with a table it does not belong to.

When fixes or rule-ignore changes are saved, the shared validation gate blocks new model errors before writing. Use --force to save and report them anyway, or tx config set validateOnSave false to disable the gate (default: on).

The default standard ruleset is a curated high-signal subset of the bundled catalog — rules that catch broken models, expensive-at-scale patterns, and a small core of consumer-experience checks. Use --ruleset full for the entire bundled catalog (including style, advisory, and heuristic rules that fire on most models).

standard also drives the deploy BPA gate, which blocks on error-severity findings by default. Error severity is therefore reserved for findings that mean the model is broken: a data column with no source column, an expression-reliant object with no expression, invalid characters in a name or description, USERELATIONSHIP against a table with row-level security, and sort-by or hierarchy columns hidden from MDX. Everything else in standard is a warning or info that bpa run reports without blocking a deploy (deploy --bpa-fail-on warning blocks on warnings too).

A few rules — high-cardinality bi-directional relationships, large unpartitioned tables, and referential-integrity violations — read VertiPaq statistics. On a model without them (no Vertipaq_* annotations), these rules are not run: bpa run lists them under "Not checked" and doesn't count them as passed. In JSON they appear in missingVertipaqStatsRules and as MissingVertipaqStats diagnostics. They don't fail the run. To check them, write the statistics into the model first with tx vertipaq --annotate --save. Statistics only exist on a deployed model, so this works on a connected model, or on a local model connected in workspace mode (the statistics are read from its deployed mirror). A model file with no deployed copy can't be checked by these rules.

The bundled catalog is embedded in the application and cannot be overridden by placing a file beside the executable. Use --rules, model rule annotations, or the bpa rules commands for explicit customization.

Models can carry their own rules: the BestPracticeAnalyzer annotation embeds rule definitions directly, and the BestPracticeAnalyzer_ExternalRuleFiles annotation lists rule files to load. Relative external-file paths resolve against the model's folder (not the current directory), and Windows-style separators (..\.devops\bpa-rules.json) work on every platform. When the same rule ID appears in more than one source, the higher-precedence source wins: ruleset < user rules (--rules, config-dir bpa-rules.json) < external files < model-embedded — so a model's own rules always override the ruleset copy. Among multiple external files, earlier entries in the annotation win. To detach a model from an external rule file, remove the annotation:

tx set . --set annotation:BestPracticeAnalyzer_ExternalRuleFiles= --save

tx bpa run
tx bpa run --errors
tx bpa run --fix --dry-run
tx bpa run --fix --save

Text output groups findings by severity. Each rule shows its object count, its name, and a line with its ID, its category and whether it is fixable. --details adds the guidance and lists the affected objects one per line. The summary line counts the findings and shows how many of the evaluated rules passed; rules that were not checked for lack of VertiPaq statistics are counted separately. Next-step commands are printed ready to copy on stderr, reusing your model path and rule options. After --fix, the output shows how many findings were fixed and remain, and whether the result was saved, staged, or kept in memory only. The rules are evaluated again after fixing, and the exit code and --fail-on apply to the findings that remain, so a run that fixes every blocking finding exits 0. JSON reports this as remaining.

--fix --dry-run previews the fixes without changing the model. Each pending fix is listed with its rule and, for a property fix, the value before and after (IsHidden: "false" → "true"); the summary says how many findings the fixes would leave. Because nothing changed, the exit code and --fail-on apply to the model as it is. JSON sets dryRun and status: "dryRun", keeps fixesApplied at 0, and adds fixesPending, wouldRemain, and a fixes array (ruleId, objectType, objectPath, action of set or delete, property, before, after), so CI can diff a preview. Without --dry-run, fixes lists the fixes that were applied.

bpa run --fix --allow-delete deletes model objects, so it asks for confirmation; --revert (drops staged work) asks too. Pass --yes to skip the prompt in scripts.

bpa rules manages rule collections:

disable and ignore check the rule ID first, so a typo can't silently turn off nothing. The ID must belong to the bundled catalog (every ruleset), your config-dir bpa-rules.json, the selected --rules-file, or, for ignore, the model's embedded or local external rules. An unknown ID fails with TOMIX_BPA_RULE_NOT_FOUND and suggests close matches. If a rule source can't be read (for example, a remote rule file, which is never fetched here), the check is skipped. Pass --allow-unknown to use an ID anyway. enable and unignore accept any ID, so you can always clean up an entry for a rule that no longer exists.

bpa rules --rules-file <file> points the subcommands at a BPA rules JSON file. bpa rules list narrows what is listed:

tx bpa rules list
tx bpa rules list model.bim --all
tx bpa rules show HIDE_FOREIGN_KEYS

Authoring rules¶

bpa rules add, set, remove, and init edit a rules JSON file: your config-dir bpa-rules.json (~/.tomix, or $TOMIX_CONFIG_DIR), which bpa run loads on every run, or the file named by bpa rules --rules-file <file>. Remote rule files can't be edited (TOMIX_BPA_RULES_FILE_REMOTE). Fields tx does not know about are kept as they are.

With set, pass only the fields to change; an empty value (--description "") removes an optional field. add creates the file when it doesn't exist; set and remove fail with TOMIX_BPA_RULES_FILE_NOT_FOUND. init won't replace an existing file unless you pass --force. Built-in rules can't be edited or removed. Turn one off with bpa rules disable, or override it by adding a rule with the same ID.

tx bpa rules add --id MEASURE_DESCRIPTIONS --name "Measures need a description" --scope Measure --expression "string.IsNullOrWhitespace(Description)"
tx bpa rules set MEASURE_DESCRIPTIONS --severity error
tx bpa rules remove MEASURE_DESCRIPTIONS
tx bpa rules --rules-file team-rules.json init

Rules that ship with the model¶

Give add, set, or remove a model (as the argument, or with --model, --recent, or --server) and they edit the model's BestPracticeAnalyzer annotation instead of a file. Those rules travel with the model, and bpa run and bpa rules list pick them up as source model-embedded. The same field checks apply, and fields tx does not know about are kept. A model and --rules-file together fail with TOMIX_BPA_RULES_TARGET_CONFLICT.

The edit is a model mutation, like bpa rules ignore: nothing is written until you pass --save (or --stage), and --save-to, --serialization, --revert, --no-sync, and --force work as they do for set. Removing the last rule removes the annotation. Rules found only under the old misspelled BestPractizeAnalyzer key are moved to the correct key on the first edit. init only creates files.

tx bpa rules add . --id MEASURE_DESCRIPTIONS --name "Measures need a description" --scope Measure --expression "string.IsNullOrWhitespace(Description)" --save
tx bpa rules set MEASURE_DESCRIPTIONS . --severity error --save
tx bpa rules remove MEASURE_DESCRIPTIONS . --save

The BPA gate also runs automatically on deploy (--skip-bpa to bypass, --fix-bpa to auto-fix first, --bpa-rules to point at specific rule files, --bpa-fail-on to lower the blocking threshold to warnings — errors block by default). The deploy gate honors bpa rules disable for the rules it loads. bpa run can load additional user and model rules, so the commands may report different findings. A rule that cannot be compiled or evaluated is itself an error-severity finding ("rule could not be evaluated: \<reason>"), so a typo in a rule expression fails bpa run and the gates instead of silently skipping the rule. On save, BPA runs only when --fix-bpa is passed; rules that cannot be evaluated block the save even when other fixes were applied. The gate never applies destructive Delete() fixes — those are only available via bpa run --fix --allow-delete.

validate — DAX and relationship integrity¶

tx validate [model] [options]

Offline analysis runs on every DAX-bearing expression (measures, calculated columns/items/tables, role filters, secondary measure expressions). Syntax is checked first: illegal characters, unterminated string/table/bracket literals and block comments, and unbalanced parentheses or braces are reported as DAX0004/DAX0005 errors. When those pass, the DAX parser reports its first grammar error: a missing comma or leftover text (DAX0007), a missing operand (DAX0008), or a VAR without = or RETURN (DAX0009). When an expression's syntax is broken, its reference checks are skipped, since a never-closed bracket makes everything after it read wrong. Syntactically valid expressions then get the offline reference checks (DAX0001–DAX0003, see error codes).

In text output each finding shows the offending expression line under its message, syntax-highlighted when it came from DAX; --no-multiline collapses the cell back to one line. Every issue carries a severity: --output-format json includes it as a string ("severity": "Error" / "Warning") on each issue, CI annotations emit errors as errors and warnings as warnings (the run still exits 1 only for errors), and the TRX projection maps each issue's severity to its test outcome.

tx validate
tx validate --ci github
tx validate --trx results.trx

The banner names the model being validated: the TOM database name, falling back to the Fabric .platform displayName, then to the file/folder name — so a nameless TMDL folder still shows its own name instead of (unnamed).

$ tx validate ./samples/basic-tmdl
Validating...
Validating: basic-tmdl

No validation errors found.

test — DAX regression tests¶

tx test [path] [options]

Runs DAX regression tests against a live model and exits 1 on any mismatch, so a pipeline can block a merge when a query result drifts. Each test is a .dax file paired with a sibling <name>.expected.json snapshot; path is a single test file or a directory searched recursively for .dax files (default: the current directory). Test names are the file paths relative to path, without the extension (totals/sales-by-region).

Like query, tests execute on a deployed model (XMLA) or a local instance — never on TMDL/BIM files. Target the model with -s <workspace> -d <model> or the active session.

Workflow. Add a test by writing a .dax file (any EVALUATE query), then record its snapshot:

tx test ./tests --update -s MyWorkspace -d MyModel   # record snapshots
tx test ./tests -s MyWorkspace -d MyModel            # verify: all PASS, exit 0

A test without a snapshot fails the run as MISS (a new test must not silently pass); a result that drifts from its snapshot fails as FAIL with a difference table. Accept an intentional change by re-running --update and committing the snapshot diff — the git diff is the review artifact.

The snapshot stores column names/types and all cell values as canonical invariant strings (null = DAX BLANK()), plus a hash of the query text used to hint when a failing test's query changed since recording:

{
  "version": 1,
  "querySha256": "9f2c…",
  "columns": [
    { "name": "Sales[Region]", "type": "string" },
    { "name": "[Total Sales]", "type": "decimal" }
  ],
  "rows": [
    ["East", "1234.50"],
    ["West", null]
  ]
}

Rows compare in order — always end test queries with ORDER BY so results are deterministic. Keep rowsets small and stable (aggregates, TOPN over ordered sets); one EVALUATE rowset per file.

tx test ./tests
tx test ./tests/totals/sales.dax --update
tx test ./tests --filter "totals/*" --trx results.trx --ci vsts

vertipaq — storage statistics¶

tx vertipaq [table] [options]

VertiPaq Analyzer-style storage statistics for a live model, with .vpax export/import for offline analysis.

tx vertipaq
tx vertipaq Sales --detail
tx vertipaq --stats --all --top 10
tx vertipaq --export stats.vpax
tx vertipaq --import stats.vpax --relationships

diff — compare two models¶

tx diff <left> <right>

Compares two models (TMDL folders or .bim files) and shows structural differences. Exit codes are CI-friendly: 0 = identical, 1 = differences found, 2 = error.

When one side is a live database, engine-computed state is ignored so that comparing source files against a processed model reports only authored changes. An inferred measure data type present on only one side, calculated-table columns present on only one side, and data type differences between calculated-table columns present on both sides are not reported. Other column property changes remain visible. Comparing two authored sources reports these differences because they may be authored changes.

tx diff ./v1.tmdl ./v2.tmdl
tx diff ./v1.bim ./v2.bim --output-format json

In JSON output, each row of data.changes has the following fields. The objectType and path meanings depend on the action:

Scripts should use this current shape until a future major release introduces objectPath and property with a deprecation window for the existing fields. The replacement schema and release timing will be decided in that later work.

doctor — environment check¶

tx doctor
tx doctor --show-details

Checks whether the local tomix environment is ready. When filing a bug, attach its output.

The report is safe to share by default: your home directory is shown as ~, and account, server, database, model, profile, and session names are replaced by what kind of thing they are (for example directory session: Power BI / Fabric workspace). Add --show-details to include them, for your own troubleshooting.

doctor is strictly local and deterministic: it checks config-directory read/write access, configuration validity, profiles, sessions (and reports stale ones, which the next tx connect <target> removes), the current session's connection, cached sign-in metadata (and, on Windows, that the matching token cache file exists), and the cached update record. It never opens the OS keystore, refreshes credentials, or contacts a model/release service. It does not create the config directory: on a machine where tx has not run yet, it reports that the directory will be created on first use. In an existing config directory it writes and deletes one temporary file to test write access. The version, how tx was installed, OS, .NET runtime, and terminal capabilities are reported in the header in both text and JSON output. A newer release is a WARN only when tx update can install it; a source build (./tx) reports it as INFO.

Each check reports one status:

OK, INFO, and WARN exit 0; any failed health check exits 1.

It remains runnable when config.json is corrupt so the report can identify the failure and direct recovery with tx config init --force.