dbt-metricflow-sql 0.2.0__tar.gz → 0.3.0__tar.gz

{dbt_metricflow_sql-0.2.0 → dbt_metricflow_sql-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dbt-metricflow-sql
-Version: 0.2.0
+Version: 0.3.0
 Summary: dbt v1 plugin for MetricFlow
 Project-URL: Documentation, https://congenial-bassoon-7zkjv8w.pages.github.io/
 License-Expression: LicenseRef-Fivetran

{dbt_metricflow_sql-0.2.0 → dbt_metricflow_sql-0.3.0}/README.md

@@ -12,6 +12,9 @@ it, so install the plugin with its `sidecar` extra:
 pip install 'dbt-metricflow-sql[sidecar]'
 ```
 
+An install from source, e.g. `pip install -e`, has no docs for `dbtsl docs` until
+`just bundle-docs` builds them: the wheel's `llms-full.txt` is a build artifact.
+
 For another command, set the `metricflow_server` var, as a list of arguments or a string:
 
 ```yaml
@@ -188,6 +191,41 @@ warns of keys it doesn't know as custom ones; the plugin declares these to it.
   naming the redirect's host. That includes the upload's, e.g. S3's for a bucket in another
   region.
 
+## Setting up dbt Cloud
+
+Before the first publish, the dbt Cloud account needs its `experimental-semantic-layer` flag on,
+which dbt Labs sets, and a **profile** for the environment to run as: a warehouse connection,
+with a **login** (its credential), which a dbt Cloud group is **mapped** to, so its users run as
+it, or a service token **granted**, as tokens ignore mappings. `dbtsl config` manages them, one
+API call per command, mostly, on the account, host and token a publish uses:
+
+```sh
+dbtsl config status       # everything set up, and every gap, each with the command filling it
+dbtsl config profiles create prod --adapter-type bigquery --connection project_id=my-project
+dbtsl config logins create --profile prod analytics_sa --keyfile ~/keys/sa.json
+dbtsl config mappings create --profile prod --login analytics_sa --group Analysts --priority 100
+dbtsl config grants create --profile prod --login analytics_sa --service-token ci
+dbtsl publish --target prod --vars '{metricflow_publish_profile: prod}'   # creates the environment
+```
+
+- `profiles`, `logins`, `mappings` and `grants` `list`, `create` and `delete`; profiles and
+  logins also `get` and `update`, keeping the fields not given. `environments` `list`,
+  `set-default` and `delete` the Semantic Layer's. Anything is named by its name or its id.
+- `create --if-missing` returns the one with the same name, or group or token and login, instead
+  of failing, so a script can run it again.
+- dbt Cloud checks the fields, and its errors are reported per field. Secrets come only from
+  files (`--keyfile`, `--private-key-file`) and environment variables (`--password-env`,
+  `--private-key-passphrase-env`, `--secret-env KEY=VAR`), go only in a login's create or update,
+  and are never printed.
+- `--json` prints one JSON document on stdout, `"schema": "dbtsl.config/v1"`, its `result` or its
+  `error`'s stable `code`. Exit codes: 0 done, 2 usage, 3 `status` found gaps, 4 token, 5
+  unavailable or 404, 6 not found, 7 rejected.
+- dbt Cloud answers these routes 404 alike whether the flag is off, the token lacks a permission,
+  or, for up to an hour after the flag is turned on, a server doesn't see it yet: a 404 is retried
+  for `--retry-for` seconds (default 120), which is safe, as nothing ran.
+
+`dbtsl docs dbt-platform-setup` has the recipe.
+
 ## Querying
 
 `dbtsl` also reads the semantic layer, from the command line:
@@ -209,6 +247,18 @@ server's default. `query` and `explain` use Trino's client protocol, `explain` a
 `EXPLAIN <query>`, which compiles without running; `search` and `get-objects` use the server's
 `/v1/search` and `/v1/objects`. SQL of `-` is read from stdin.
 
+`query` and `explain` read their SQL in the target's dialect, e.g. BigQuery's
+`DATE_TRUNC(date, YEAR)` for a BigQuery target, as a MetricFlow model's is, so a query reads the
+same with `--local` as without. `--dialect` names another, e.g. `--dialect trino` for Trino's
+`DATE_TRUNC('year', date)`: any of sqlglot's dialects, case-insensitively. The server answers an
+unknown one with an error, which the command fails with. Either way, the SQL compiles to the
+warehouse's dialect. The server is told the dialect as `X-Dbt-Dialect`; Trino clients that don't
+send it are read as Trino's.
+
+```sh
+dbtsl query --dialect trino "SELECT DATE_TRUNC('year', date) AS year, AGG(revenue) FROM sales GROUP BY 1"
+```
+
 With `--local`, they parse the project, and read its own semantics instead, as `dbt build`
 would compile them, on the server the plugin runs to compile MetricFlow models: `query` compiles the SQL there
 and runs it on the target's warehouse, with dbt's own adapter, so the tables it reads must be

{dbt_metricflow_sql-0.2.0 → dbt_metricflow_sql-0.3.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "dbt-metricflow-sql"
 # A placeholder: a release sets its tag's version, with scripts/set_version.py.
-version = "0.2.0"
+version = "0.3.0"
 description = "dbt v1 plugin for MetricFlow"
 # Its PyPI page: README.md is for this repository.
 readme = "PYPI.md"

{dbt_metricflow_sql-0.2.0 → dbt_metricflow_sql-0.3.0}/src/dbt_metricflow_sql/cli.py

@@ -12,12 +12,16 @@
 - `dbtsl get-objects ID...`: prints the semantic layer's objects by id, as JSON.
 - `dbtsl docs [PAGE]`: prints MetricFlow's docs, as Markdown, for AI agents: with no page, the
   pages it has; with `--all`, every page.
+- `dbtsl config profiles|logins|mappings|grants|environments|status`: sets up the dbt Cloud
+  account's Semantic Layer for the project to publish to (see `dbt_metricflow_sql.sl_config`).
 
 Each of the last four reads the server and environment the project publishes to, with the same
 vars and token, the environment naming the Trino catalog: it loads the project's and profile's
 config, with the dbt arguments it's given, e.g. `--target prod`, without parsing the project, so
 nothing else in the project, e.g. a model that doesn't parse, can fail it. Queries run on the
-server, over Trino's protocol, and so does `explain`, as `EXPLAIN <query>`. With `--local`, it
+server, over Trino's protocol, and so does `explain`, as `EXPLAIN <query>`, their SQL read in the
+target's dialect, e.g. BigQuery's, as a MetricFlow model's is, or in the one `--dialect` names,
+e.g. `--dialect trino`. With `--local`, it
 parses the project, quietly, and reads its own semantics instead, on the server the plugin runs
 to compile MetricFlow models; a query runs on the target's warehouse, through dbt's adapter. SQL
 of `-` is read from stdin.
@@ -47,7 +51,7 @@ from dbt_common.clients.system import get_env
 from dbt_common.context import set_invocation_context
 from dbt_common.exceptions import DbtRuntimeError
 
-from dbt_metricflow_sql import client, plugin
+from dbt_metricflow_sql import client, plugin, sl_config
 from dbt_metricflow_sql.client import MetricFlowError, QueryResult
 from dbt_metricflow_sql.docs import DocsMissingError, DocsPage, read_docs, split_pages
 from dbt_metricflow_sql.semantics import SemanticsError
@@ -77,8 +81,12 @@ def main(argv: Sequence[str] | None = None) -> int:
         parser.error(f"unrecognized arguments: {' '.join(extra)}")
     if args.command == DOCS:
         return _docs(args.page, args.all)
+    if args.command == sl_config.CONFIG:
+        return sl_config.run(args, _load_config)
     reader: _Reader | None = (
-        _local_reader(args.dbt_args) if args.local else _remote_reader(args.dbt_args)
+        _local_reader(args.dbt_args, args.dialect)
+        if args.local
+        else _remote_reader(args.dbt_args, args.dialect)
     )
     if reader is None:
         return 1
@@ -121,10 +129,12 @@ def _parser() -> argparse.ArgumentParser:
         ),
     )
     query = _reading_command(commands, QUERY, "run semantic SQL, printing its result")
+    _add_dialect(query)
     query.add_argument("sql", help="the semantic SQL to run, or `-` to read it from stdin")
     explain = _reading_command(
         commands, EXPLAIN, "compile semantic SQL, printing the warehouse SQL it compiles to"
     )
+    _add_dialect(explain)
     explain.add_argument("sql", help="the semantic SQL to compile, or `-` to read it from stdin")
     search = _reading_command(commands, SEARCH, "search the semantic layer's objects")
     search.add_argument("query", nargs="+", help="keywords, e.g. `return rate`")
@@ -145,9 +155,22 @@ def _parser() -> argparse.ArgumentParser:
     )
     docs.add_argument("page", nargs="?", help="the page to print, e.g. `concepts`")
     docs.add_argument("--all", action="store_true", help="print every page")
+    sl_config.add_parser(commands, _add_dbt_options)
     return parser
 
 
+def _add_dbt_options(command: argparse.ArgumentParser, options: Sequence[str]) -> None:
+    """dbt's `options`, e.g. `--target`, collected into `dbt_args` in the order given."""
+    command.set_defaults(dbt_args=[])
+    for option in options:
+        command.add_argument(
+            option,
+            action=_PassToDbt,
+            metavar=option.lstrip("-").upper(),
+            help="as dbt's own option",
+        )
+
+
 def _reading_command(
     commands: argparse._SubParsersAction[argparse.ArgumentParser], name: str, summary: str
 ) -> argparse.ArgumentParser:
@@ -168,7 +191,8 @@ def _reading_command(
             " queries on the target's warehouse with dbt's adapter"
         ),
     )
-    command.set_defaults(dbt_args=[])
+    # Only `query` and `explain` take `--dialect`.
+    command.set_defaults(dbt_args=[], dialect=None)
     for option in _DBT_OPTIONS:
         command.add_argument(
             option,
@@ -179,6 +203,21 @@ def _reading_command(
     return command
 
 
+def _add_dialect(command: argparse.ArgumentParser) -> None:
+    """`--dialect`, the dialect the command's SQL is written in, instead of the target's."""
+    command.add_argument(
+        "--dialect",
+        # Case-insensitive, e.g. `BigQuery`, as the server's statements are, though `/v1/compile`'s
+        # aren't. The server checks the name, so it's not checked here.
+        type=str.lower,
+        metavar="DIALECT",
+        help=(
+            "the SQL dialect the semantic SQL is written in, e.g. `trino` or `bigquery`"
+            " (default: the target's, e.g. `bigquery` for a BigQuery target)"
+        ),
+    )
+
+
 class _PassToDbt(argparse.Action):
     """Collects an option, e.g. `--target prod`, into `dbt_args`, in the order given."""
 
@@ -215,9 +254,16 @@ class _RemoteReader:
     """Reads the environment the project publishes to, on the server it publishes to."""
 
     layer: plugin.SemanticLayer
+    # The dialect queries are written in, if not the target's (see `SemanticLayer.input_dialect`).
+    dialect: str | None = None
 
     def query(self, sql: str) -> QueryResult:
-        return client.run_query(self.layer.url, sql, self.layer.headers)
+        return client.run_query(
+            self.layer.url,
+            sql,
+            self.layer.headers,
+            input_dialect=self.dialect or self.layer.input_dialect,
+        )
 
     def explain(self, sql: str) -> str:
         # The server compiles `EXPLAIN <query>` without running it, in the environment's dialect.
@@ -240,9 +286,11 @@ class _LocalReader:
     manifest: Manifest
     # The invocation's, as the plugin's own hooks find it.
     config: RuntimeConfig
+    # The dialect queries are written in, if not the target's.
+    dialect: str | None = None
 
     def query(self, sql: str) -> QueryResult:
-        compiled = plugin.compile_locally(self.manifest, self.config, sql)
+        compiled = plugin.compile_locally(self.manifest, self.config, sql, self.dialect)
         if compiled.explain:
             # As the server answers `EXPLAIN <query>`: its compiled SQL, without running it.
             return QueryResult(
@@ -262,7 +310,7 @@ class _LocalReader:
         )
 
     def explain(self, sql: str) -> str:
-        return plugin.compile_locally(self.manifest, self.config, sql).sql
+        return plugin.compile_locally(self.manifest, self.config, sql, self.dialect).sql
 
     def search(self, query: str, limit: int) -> tuple[client.SearchHit, ...]:
         return client.search(plugin.local_url(self.manifest, self.config), query, limit)
@@ -271,13 +319,13 @@ class _LocalReader:
         return client.get_objects(plugin.local_url(self.manifest, self.config), ids)
 
 
-def _remote_reader(dbt_args: Sequence[str]) -> _RemoteReader | None:
+def _remote_reader(dbt_args: Sequence[str], dialect: str | None = None) -> _RemoteReader | None:
     """
     The reader of the server the project publishes to, from its config alone (see
     `_load_config`), or None, reporting why, if it can't find the server.
     """
     try:
-        return _RemoteReader(plugin.semantic_layer(_load_config(dbt_args)))
+        return _RemoteReader(plugin.semantic_layer(_load_config(dbt_args)), dialect)
     except click.ClickException as error:
         # dbt's own option's, e.g. `--vars` that isn't YAML.
         print(error.format_message(), file=sys.stderr)
@@ -306,10 +354,10 @@ def _load_config(dbt_args: Sequence[str]) -> RuntimeConfig:
     return RuntimeConfig.from_args(flags)
 
 
-def _local_reader(dbt_args: Sequence[str]) -> _LocalReader | None:
+def _local_reader(dbt_args: Sequence[str], dialect: str | None = None) -> _LocalReader | None:
     """The reader of the project `dbt parse` parses, quietly, or None if it fails, as dbt logs."""
     parsed = _parse(dbt_args, quiet=True)
-    return None if parsed is None else _LocalReader(*parsed)
+    return None if parsed is None else _LocalReader(*parsed, dialect)
 
 
 def _parse(dbt_args: Sequence[str], quiet: bool = False) -> tuple[Manifest, RuntimeConfig] | None:

{dbt_metricflow_sql-0.2.0 → dbt_metricflow_sql-0.3.0}/src/dbt_metricflow_sql/client.py

@@ -26,6 +26,9 @@ PROFILE_HEADER = "X-Dbt-Profile"
 # The header naming the catalog, i.e. the environment, a query, compile, search or lookup reads, as
 # Trino's protocol names a session's catalog, e.g. `prod`. Without it, the server reads its default.
 TRINO_CATALOG_HEADER = "X-Trino-Catalog"
+# The header naming the dialect a query's semantic SQL is written in, e.g. `bigquery`. Without it,
+# the server reads it as Trino's; it answers one it doesn't know with an error.
+DIALECT_HEADER = "X-Dbt-Dialect"
 # Trino's protocol requires a user; the server identifies the caller by its token instead.
 _TRINO_USER_HEADER = "X-Trino-User"
 _TRINO_USER = "dbtsl"
@@ -60,13 +63,16 @@ class Compiled:
     explain: bool = False
 
 
-def compile_sql(url: str, sql: str, dialect: str) -> Compiled:
-    """Metricflow SQL, in the warehouse's `dialect`, to warehouse SQL, pretty-printed."""
+def compile_sql(url: str, sql: str, dialect: str, input_dialect: str | None = None) -> Compiled:
+    """
+    Metricflow SQL, in `input_dialect` if given, else the warehouse's `dialect`, to warehouse SQL,
+    pretty-printed.
+    """
     response = _request(
         url,
         "POST",
         "/v1/compile",
-        {"sql": sql, "input_dialect": dialect, "output_dialect": dialect},
+        {"sql": sql, "input_dialect": input_dialect or dialect, "output_dialect": dialect},
     ).body
     return Compiled(
         sql=str(response["sql"]),
@@ -175,14 +181,22 @@ class QueryResult:
     numeric: tuple[bool, ...]
 
 
-def run_query(url: str, sql: str, headers: Mapping[str, str] | None = None) -> QueryResult:
+def run_query(
+    url: str,
+    sql: str,
+    headers: Mapping[str, str] | None = None,
+    input_dialect: str | None = None,
+) -> QueryResult:
     """
     Runs the semantic SQL `sql` on the server at `url`, over Trino's client protocol: submits it
     to `/v1/statement`, then follows each response's `nextUri` until there is none, collecting its
     rows. A `nextUri` is requested from `url`'s own scheme and host, whatever it names, so
-    `headers`, e.g. credentials, never go elsewhere. Raises `MetricFlowError` if the query fails.
+    `headers`, e.g. credentials, never go elsewhere. `sql` is read in `input_dialect`, e.g.
+    `bigquery`, if given, else as Trino's. Raises `MetricFlowError` if the query fails.
     """
     request_headers = {**(headers or {}), _TRINO_USER_HEADER: _TRINO_USER}
+    if input_dialect:
+        request_headers[DIALECT_HEADER] = input_dialect
     results = _request(
         url,
         "POST",

{dbt_metricflow_sql-0.2.0 → dbt_metricflow_sql-0.3.0}/src/dbt_metricflow_sql/llms-full.txt

@@ -26,9 +26,9 @@
 
    1. [Signup](https://www.getdbt.com/signup) if you don’t already have an account.
 
-   2. Configure a data warehouse connection
+   2. Set up [dbt Platform CLI](https://docs.getdbt.com/docs/platform/dbt-cli-installation)
 
-   3. Set up [dbt Platform CLI](https://docs.getdbt.com/docs/platform/dbt-cli-installation)
+   3. [Configure the Semantic Layer in dbt Platform](../dbt-platform-setup/)
 
 4. **Model your data**
 
@@ -63,6 +63,67 @@
 
    To compile queries locally, use the `--local` flag on CLI commands:
 
+# dbt Platform setup
+
+> Set up dbt Cloud's Semantic Layer for a project with `dbtsl config`, from the command line.
+
+Before a project publishes to dbt Cloud’s Semantic Layer for the first time, its account needs:
+
+* a **profile**: a warehouse connection, which an environment runs as;
+* a **login** on the profile: the warehouse credential queries run with;
+* a **mapping** from a dbt Cloud group to the login, so the group’s users run as it. A user in several mapped groups runs as the login of the mapping with the highest priority;
+* or a **grant** of the login to a service token. Service tokens ignore mappings.
+
+dbt Labs turns on the account’s `experimental-semantic-layer` flag. Then `dbtsl config` sets up the rest, and the first `dbtsl publish` creates the environment on the profile. The account’s first environment becomes its default.
+
+## The recipe
+
+Start with `status`. It is read-only, and it reports every gap, each with the command that fills it. Its UPPERCASE arguments are placeholders to fill in.
+
+```sh
+dbtsl config status
+```
+
+1. Create the profile. Name it after the target that publishes, e.g. `prod`, or set the `metricflow_publish_profile` var to its name.
+
+   ```sh
+   dbtsl config profiles create prod --adapter-type bigquery \
+     --connection project_id=my-project --if-missing
+   # Snowflake:
+   dbtsl config profiles create prod --adapter-type snowflake --connection account=ab12345 \
+     --connection database=ANALYTICS --connection warehouse=REPORTING --if-missing
+   ```
+
+2. Create a login with its secret. Secrets come only from files and environment variables, and are never printed.
+
+   ```sh
+   dbtsl config logins create --profile prod analytics_sa --keyfile ~/keys/sa.json --if-missing
+   # Snowflake, with a key pair, or `--password-env VAR`:
+   dbtsl config logins create --profile prod reporter --login-detail user=REPORTER \
+     --login-detail role=REPORTER --private-key-file ~/keys/reporter.p8 \
+     --private-key-passphrase-env SNOWFLAKE_PASSPHRASE --if-missing
+   ```
+
+3. Map a group to the login, or grant the login to a service token, e.g. CI’s. Groups and service tokens are named by their name or id.
+
+   ```sh
+   dbtsl config mappings create --profile prod --login analytics_sa \
+     --group Analysts --priority 100 --if-missing
+   dbtsl config grants create --profile prod --login analytics_sa --service-token ci --if-missing
+   ```
+
+4. Publish. This creates the environment on the profile.
+
+   ```sh
+   dbtsl publish --target prod --vars '{metricflow_publish_profile: prod}'
+   ```
+
+Then `dbtsl config status` reports `Ready.`
+
+## Details
+
+Each command’s options are in its help: `dbtsl config --help`, and e.g. `dbtsl config logins create --help`.
+
 # Overview
 
 MetricFlow is the engine that powers the dbt semantic layer.

{dbt_metricflow_sql-0.2.0 → dbt_metricflow_sql-0.3.0}/src/dbt_metricflow_sql/plugin.py

@@ -150,9 +150,9 @@ class MetricflowManager:
         # The server, once something needs it; or what kept it from starting.
         self._server: ServerProcess | None = None
         self._start_failure: MetricFlowError | SemanticsError | None = None
-        # Compilations by dialect and semantic SQL, so a model compiles once, as dbt builds its
+        # Compilations by dialect, input dialect and semantic SQL, so a model compiles once, as dbt builds its
         # graph, however many times dbt compiles it.
-        self._compiled: dict[tuple[str, str], Compiled] = {}
+        self._compiled: dict[tuple[str, str | None, str], Compiled] = {}
         # The physical tables each model's compiled SQL reads, by unique id.
         self.tables: dict[str, tuple[tuple[str, ...], ...]] = {}
 
@@ -199,15 +199,22 @@ class MetricflowManager:
             raise MetricFlowError(f"starting the server failed: {failure}") from failure
         return server.url
 
-    def compile(self, manifest: Manifest, config: RuntimeConfig, sql: str) -> Compiled:
+    def compile(
+        self,
+        manifest: Manifest,
+        config: RuntimeConfig,
+        sql: str,
+        input_dialect: str | None = None,
+    ) -> Compiled:
+        """Compiles `sql`, in `input_dialect` if given, else the warehouse's, to the warehouse's."""
         url = self.url(manifest, config)
         # dbt's adapter types are sqlglot's dialect names: bigquery, duckdb, snowflake, ...
-        key = (config.credentials.type, sql)
+        key = (config.credentials.type, input_dialect, sql)
         with self._lock:
             compiled = self._compiled.get(key)
         # Outside the lock, so models compile concurrently on dbt's threads.
         if compiled is None:
-            compiled = client.compile_sql(url, sql, config.credentials.type)
+            compiled = client.compile_sql(url, sql, config.credentials.type, input_dialect)
             with self._lock:
                 self._compiled[key] = compiled
         return compiled
@@ -353,10 +360,20 @@ def _publish_target(config: RuntimeConfig, publishing: str) -> _PublishTarget |
 
 def _dbt_cloud_target(config: RuntimeConfig) -> _PublishTarget:
     """
-    The Semantic Layer of the dbt Cloud account of the project's entry in `DBT_CLOUD_CONFIG`, with
-    the entry's token. The entry is `dbt_project.yml`'s `dbt-cloud: project-id`, else the file's
-    active project. Raises `MetricFlowError` naming what's missing. Never echoes the file, which
-    holds tokens: YAML's errors quote the line they're on.
+    The Semantic Layer of the dbt Cloud account of the project's entry in `DBT_CLOUD_CONFIG` (see
+    `_dbt_cloud_entry`), with the entry's token.
+    """
+    entry = _dbt_cloud_entry(config)
+    host = str(entry.get("account-host") or "")
+    token = str(entry.get("token-value") or "").strip() or None
+    return _PublishTarget(_semantic_layer_url(host), token)
+
+
+def _dbt_cloud_entry(config: RuntimeConfig) -> dict[str, Any]:
+    """
+    The project's entry in `DBT_CLOUD_CONFIG`: `dbt_project.yml`'s `dbt-cloud: project-id`, else
+    the file's active project. Raises `MetricFlowError` naming what's missing. Never echoes the
+    file, which holds tokens: YAML's errors quote the line they're on.
     """
     path = DBT_CLOUD_CONFIG
     try:
@@ -387,10 +404,8 @@ def _dbt_cloud_target(config: RuntimeConfig) -> _PublishTarget:
     ]
     if not entries:
         raise MetricFlowError(f"{path} has no project {str(project_id).strip()}")
-    entry = entries[0]
-    host = str(entry.get("account-host") or "")
-    token = str(entry.get("token-value") or "").strip() or None
-    return _PublishTarget(_semantic_layer_url(host), token)
+    entry: dict[str, Any] = entries[0]
+    return entry
 
 
 def _semantic_layer_url(account_host: str) -> str:
@@ -548,14 +563,18 @@ class SemanticLayer:
     url: str
     # The token, and the catalog naming the environment, if any.
     headers: Mapping[str, str] = field(repr=False)
+    # The dialect queries' semantic SQL is written in: the target warehouse's, e.g. `bigquery`, as
+    # a MetricFlow model's is, so a query reads the same here as with `--local`.
+    input_dialect: str | None = None
 
 
 def semantic_layer(config: RuntimeConfig) -> SemanticLayer:
     """
     The server the project publishes to (see `_publish_target`), whatever the `metricflow_publish`
     var says, with the headers reading the environment it publishes to there: the token (see
-    `_token_headers`), and the environment (see `_environment`) as the Trino catalog. Raises
-    `MetricFlowError` for a server it can't find, or a header it can't send.
+    `_token_headers`), and the environment (see `_environment`) as the Trino catalog; queries are
+    read in the target's dialect. Raises `MetricFlowError` for a server it can't find, or a header
+    it can't send.
     """
     target = _publish_target(config, _Publishing.REQUIRED)
     assert target is not None, "a required publish always has a target"
@@ -565,7 +584,78 @@ def semantic_layer(config: RuntimeConfig) -> SemanticLayer:
             ((f"the `{ENVIRONMENT_VAR}` var", client.TRINO_CATALOG_HEADER, _environment(config)),),
         )
     )
-    return SemanticLayer(url=target.url, headers=headers)
+    # dbt's adapter types are sqlglot's dialect names: bigquery, duckdb, snowflake, ...
+    return SemanticLayer(url=target.url, headers=headers, input_dialect=config.credentials.type)
+
+
+@dataclass(frozen=True)
+class DbtCloudAccount:
+    """The dbt Cloud account the project publishes to, for `dbtsl config` to set up."""
+
+    # dbt Cloud's API, e.g. `https://ab123.us1.dbt.com`.
+    api_url: str
+    account_id: int
+    # The headers authenticating to `api_url`: the bearer token.
+    api_headers: Mapping[str, str] = field(repr=False)
+    # Where the token came from, e.g. `DBT_CLOUD_TOKEN`; never the token itself.
+    token_source: str
+    # The server the project publishes to (see `_publish_target`), and the headers authenticating
+    # to it, as a publish sends them.
+    semantic_layer_url: str
+    semantic_layer_headers: Mapping[str, str] = field(repr=False)
+
+
+def dbt_cloud_account(
+    config: RuntimeConfig, account_host: str | None = None, account_id: str | None = None
+) -> DbtCloudAccount:
+    """
+    The dbt Cloud account of the project's entry in `DBT_CLOUD_CONFIG` (see `_dbt_cloud_entry`),
+    or of `account_host` and `account_id` where they're given, then not needing the file. The
+    token is `PUBLISH_TOKEN_ENV`, else the entry's. A host may name its scheme: `http://` only for
+    this machine's, e.g. a test's. Raises `MetricFlowError` naming what's missing.
+    """
+    entry: Mapping[str, Any] = {}
+    if account_host is None or account_id is None:
+        entry = _dbt_cloud_entry(config)
+    host = (account_host or str(entry.get("account-host") or "")).strip().rstrip("/")
+    if not host:
+        raise MetricFlowError(f"{DBT_CLOUD_CONFIG}'s project has no `account-host`")
+    raw_id = (account_id or str(entry.get("account-id") or "")).strip()
+    # ASCII digits only, as `_project_id`'s.
+    if not re.fullmatch(r"[0-9]+", raw_id) or int(raw_id) == 0:
+        raise MetricFlowError("dbt Cloud's account id must be a positive integer")
+    scheme, separator, _ = host.partition("://")
+    api_url = host if separator and scheme in ("http", "https") else f"https://{host}"
+    entry_token = str(entry.get("token-value") or "").strip() or None
+    token_source = str(DBT_CLOUD_CONFIG)
+    if os.environ.get(PUBLISH_TOKEN_ENV, "").strip():
+        token_source = PUBLISH_TOKEN_ENV
+    api_headers = _token_headers(_PublishTarget(api_url, entry_token))
+    if not api_headers:
+        raise MetricFlowError(
+            f"setting up dbt Cloud needs a token: `{PUBLISH_TOKEN_ENV}`, or {DBT_CLOUD_CONFIG}'s"
+        )
+    # As a publish finds its server: the var's gets only `PUBLISH_TOKEN_ENV`.
+    url = _rendered_var(config, PUBLISH_URL_VAR)
+    target = _PublishTarget(url) if url else _PublishTarget(_semantic_layer_url(host), entry_token)
+    return DbtCloudAccount(
+        api_url=api_url,
+        account_id=int(raw_id),
+        api_headers=api_headers,
+        token_source=token_source,
+        semantic_layer_url=target.url,
+        semantic_layer_headers=_token_headers(target),
+    )
+
+
+def publish_environment(config: RuntimeConfig) -> str:
+    """The MetricFlow environment the project publishes to (see `_environment`)."""
+    return _environment(config)
+
+
+def publish_profile(config: RuntimeConfig) -> str | None:
+    """The dbt Cloud profile a publish creates its environment on: the `PROFILE_VAR` var."""
+    return _rendered_var(config, PROFILE_VAR)
 
 
 def local_url(manifest: Manifest, config: RuntimeConfig) -> str:
@@ -577,9 +667,14 @@ def local_url(manifest: Manifest, config: RuntimeConfig) -> str:
     return _manager.url(manifest, config)
 
 
-def compile_locally(manifest: Manifest, config: RuntimeConfig, sql: str) -> Compiled:
-    """Compiles semantic SQL as a MetricFlow model's is, on the server `local_url` runs."""
-    return _manager.compile(manifest, config, sql)
+def compile_locally(
+    manifest: Manifest, config: RuntimeConfig, sql: str, input_dialect: str | None = None
+) -> Compiled:
+    """
+    Compiles semantic SQL as a MetricFlow model's is, on the server `local_url` runs: read in
+    `input_dialect` if given, else the warehouse's.
+    """
+    return _manager.compile(manifest, config, sql, input_dialect)
 
 
 @dataclass(frozen=True)