Get Help

invoke_command

Runs one command — typically a SQL query — against a data source of the open project and returns the rows as a list of dicts.

Signature 

cat.invoke_command(data_source_name: str, command_text: str, logging_level: LoggingLevel = None) -> dict

Parameters

Parameter Type Default Meaning
data_source_name str required Name of a data source of the open project — exact, case-sensitive, as in the project file.
command_text str required The command to run — SQL, DAX or whatever the data source’s provider understands.
logging_level LoggingLevel None cat.LoggingLevel member; used only when this is the first call of the process. See Logging.

What it does

Sends the command through the data source exactly as the tests would — same provider, same connection string, same expanded environment variables — and returns what comes back, translated to Python. It is a troubleshooting tool: what does this query return through CAT, with this connection? — handy for data sources without a query tool of their own (Excel, CSV) and for checking a connection string without writing a test. It is not a data export: the whole result is loaded into memory. A failing command does not raise — the error comes back in the result.

Returns

A dict with three keys:

Key Value
data list[dict] — one dict per row, column name → value (values are the provider’s types; None for NULL). Ready for pandas.DataFrame(result["data"]).
messages A .NET collection of CommandMessage objects (Timestamp, Message) — informational messages from the provider, for SQL Server the PRINT output, for example.
exception The .NET exception when the command failed, otherwise None. Check it: the call itself returns either way.

Raises

The sign-in and plan check (first call of the process) raises the CatPortalError family listed on the Introduction page. System.Exception: There is no open CAT project. Open a project first. with no open project; System.Exception: The provided data source name '…' was not found. Only data sources with these names are available: … for an unknown name. A failing command is not raised — see exception above.

Examples 

cat.open_project("D:/Testing/Aero.cat.yaml")
r = cat.invoke_command("AERO_PROD", "SELECT * FROM DIM.GATES")
if r["exception"] is not None:
    print(r["exception"].Message)
for row in r["data"]:
    print(row)

import pandas as pd
df = pd.DataFrame(r["data"])
← get_tests
invoke_project →