Invoke-CatCommand
Runs one command — typically a SQL query — against a data source of the open project and returns the rows, messages and error as one object.
Synopsis
Invoke-CatCommand [-DataSourceName] <string> [-Command] <string>
Parameters
| Parameter | Type | Position | Default | Meaning |
|---|---|---|---|---|
-DataSourceName |
string | 0 | required | Name of a data source of the open project (exact name, as in the project file). |
-Command |
string | 1 | required | The command to run — SQL, DAX or whatever the data source’s provider understands. |
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. 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. A failing command does not make the cmdlet fail — the error comes back in the result.
Output
One CommandResult object:
| Property | Meaning |
|---|---|
Data |
A System.Data.DataTable with the result set — .Rows, .Columns; pipe it to Format-Table, Out-GridView or Export-Csv (select the columns first to drop the DataRow bookkeeping properties). |
Messages |
Informational messages from the provider (Timestamp, Message) — for SQL Server the PRINT output, for example. |
Exception |
The error when the command failed, otherwise empty. Check it: the cmdlet itself succeeds either way. |
Errors
There is no CAT session active… / There is no open CAT project. Open a project first. when nothing is open; 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 an error of the cmdlet — see Exception above.
Examples
Open-CatProject -Path 'D:\Testing\Aero.cat.yaml'
$r = Invoke-CatCommand -DataSourceName AERO_PROD -Command 'SELECT * FROM DIM.GATES'
$r.Data | Format-Table
if ($r.Exception) { $r.Exception.Message }
# to a CSV
$r.Data | Select-Object GateCode, Terminal, Capacity | Export-Csv gates.csv -NoTypeInformation
Related
- Introduction — session model, logging, errors, sign-in.
- Data sources and Providers — what each provider accepts as a command.
Get-CatDataSource— the names to use.