---
title: "invoke_command"
description: "invoke_command — run one command against a data source of the open project."
url: "https://docs.justcat.it/reference/python-module/invoke-command/"
---
# invoke_command

## Signature

```python
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](https://docs.justcat.it/reference/python-module/introduction/#logging "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](https://docs.justcat.it/reference/python-module/introduction/ "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

```python
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"])
```

## Related

- [Introduction](https://docs.justcat.it/reference/python-module/introduction/ "Introduction") — session model, logging, .NET objects, exceptions, sign-in.
- [Data sources](https://docs.justcat.it/reference/data-sources/ "Data sources") and [Providers](https://docs.justcat.it/reference/data-sources/providers/ "Providers") — what each provider accepts as a command.
- [`get_data_sources`](https://docs.justcat.it/reference/python-module/get-data-sources/ "get_data_sources") — the names to use.