ping_data_source
Opens one data source the way a test would, proves it answers, and returns the verdict as a dict — with the driver's own error when it does not.
Signature
cat.ping_data_source(data_source_name: 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. |
logging_level |
LoggingLevel | None |
cat.LoggingLevel member; used only when this is the first call of the process. See Logging. |
What it does
Does what the data source’s provider does when a test uses it, with a harmless statement in place of a real one. What counts as answering depends on the provider:
| Provider | What the test proves |
|---|---|
| SQL Server, PostgreSQL, MySQL, ClickHouse, Snowflake, Teradata, Databricks, Oracle, DuckDB@1 | Connects, runs a one-row statement (SELECT 'cat' AS cat, with FROM DUAL for Oracle) and reads the row. |
| DAX and Power BI providers (Windows) | Connects and reads the row of EVALUATE ROW("cat", "cat"). |
| ODBC, and the OleDb CSV and Excel providers (Windows) | Opens the connection and stops; no statement is run. |
| Excel@1, YAML | The file exists. The file is not read. |
| Csv@1 | The folder exists. |
| Excel@2 | The workbook file exists. It is not loaded — that is what a run does, and it can take seconds on a large file. |
| Csv@2 | At least one file matches the connection string. A pattern that matches nothing is caught only when no other entry of the list matches either. |
The statement has a fixed timeout of 30 seconds; opening the connection is bounded by the driver’s own connect timeout from the connection string, and there are no retries. A Databricks SQL warehouse or cluster that was stopped starts on the first query and can take minutes: the message says it may still be starting, so test again a few minutes later.
Returns
A dict:
| Key | Value |
|---|---|
name |
The data source name as written in the project; (unnamed) when there is none. |
provider |
The provider and version, as written, for example SqlServer@2. |
success |
True when the data source answered. |
message |
What was proven (Connected and read one row, File exists: …), or the error. |
duration_seconds |
float. |
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 data source that does not answer is not raised — success is False and message holds the reason.
Examples
cat.open_project("D:/Testing/Aero.cat.yaml")
r = cat.ping_data_source("AERO_PROD")
if not r["success"]:
print(r["message"])
Related
- Introduction — session model, logging, .NET objects, exceptions, sign-in.
ping_data_sources— all data sources of the project at once.invoke_command— run a statement of your own once the data source answers.