preset-cli 0.2.20

运行SQL

CLI提供了一种简单的方式来在工作空间中运行SQL分析数据库。这可以通过程序化或交互式方式进行。例如，给定工作空间URL和数据库名称，要运行查询 SELECT COUNT(*) AS revenue FROM sales，您可以运行

% preset-cli --workspaces=https://abcdef12.us1a.app.preset.io/ superset sql \
> --database-id=1 -e "SELECT COUNT(*) AS revenue FROM sales"

https://abcdef12.us1a.app.preset.io/
  revenue
---------
       42

如果您没有指定数据库名称，您将看到可用的数据库列表以供选择。如果您没有通过-e选项指定SQL查询，CLI将启动一个简单的REPL（读取-评估-打印循环），您可以在其中交互式地运行查询。

从导出同步

您可以使用CLI管理工作空间资源（数据库、数据集、图表和仪表板）的源代码控制。配置应存储为YAML文件，使用Apache Superset导入和导出资源相同的格式。

生成配置文件的简单方法是，在一个预设工作空间中构建一个或多个仪表板，将它们一起导出，然后将生成的文件解压到目录中。

解压后，目录应如下所示

• charts/

• dashboards/

• databases/

• datasets/

• metadata.yaml

您可以在这里看到一个示例。

要将这些文件同步到预设工作空间，您只需运行

% preset-cli --workspaces=https://abcdef12.us1a.app.preset.io/ \
> superset sync native /path/to/directory/

如果任何资源已存在，您需要传递--overwrite标志以替换它们。如果未传递标志，CLI将警告您任何已存在的资源。

% preset-cli --workspaces=https://abcdef12.us1a.app.preset.io/ \
> superset sync native /path/to/directory/
Error importing database
The following file(s) already exist. Pass --overwrite to replace them.
- databases/Google_Sheets.yaml
Error importing dataset
The following file(s) already exist. Pass --overwrite to replace them.
- datasets/Google_Sheets/country_cnt.yaml
Error importing chart
The following file(s) already exist. Pass --overwrite to replace them.
- charts/Total_count_134.yaml
Error importing dashboard
The following file(s) already exist. Pass --overwrite to replace them.
- dashboards/White_label_test.yaml

通过将--disallow-edits标志传递给命令，可以将同步的资源标记为“外部管理”。当传递此标志时，用户将无法编辑资源。还可以提供资源的修改URL，例如，指向GitHub存储库中的文件的链接。这可以通过传递--external-url-prefix标志来完成。

% preset-cli --workspaces=https://abcdef12.us1a.app.preset.io/ \
> superset sync native /path/to/directory/ --disallow-edits \
> --external-url-prefix=https://github.com/org/project/blob/master/

这样，文件dashboards/White_label_test.yaml将有一个指向https://github.com/org/project/blob/master/dashboards/White_label_test.yaml的外部URL。目前，此URL尚未在任何地方显示，但在不久的将来，我们应该从实例UI中提供指向它的便捷途径。

slice_name: Total sales
viz_type: big_number_total
params:
  metric: sum__sales
  adhoc_filters: []

{% if country %}
slice_name: Sales in {{ country }}
{% else %}
slice_name: Total sales
{% endif %}
viz_type: big_number_total
params:
  metric: sum__sales
  {% if country %}
  adhoc_filters:
    - clause: WHERE
      expressionType: SQL
      sqlExpression: country = '{{ country }}'
      subject: null
      operator: null
      comparator: null
  {% else %}
  adhoc_filters: []
  {% endif %}

% preset-cli --workspaces=https://abcdef12.us1a.app.preset.io/ \
> superset sync native /path/to/directory/ -o country=BR

params:
  metric: sum__sales
  adhoc_filters:
    - clause: WHERE
      expressionType: SQL
      {% if instance.host == '//abcdef12.us1a.app.preset.io/ %}
      sqlExpression: warehouse_id = 1
      {% elif instance.host == '//34567890.us1a.app.preset.io/ %}
      sqlExpression: warehouse_id = 2
      {% else %}
      sqlExpression: warehouse_id = 3
      {% endif %}

database_name: Postgres
sqlalchemy_uri: postgres://{{ env["POSTGRES_HOSTNAME"] }}

# functions/demo.py
def hello_world() -> str:
    return "Hello, world!"

slice_name: {{ functions.demo.hello_world() }}
viz_type: big_number_total
params:
  ...

sql: 'SELECT action, count(*) as times
    FROM logs
    {% if filter_values(''action_type'')|length %}
        WHERE action is null
        {% for action in filter_values(''action_type'') %}
            or action = ''{{ action }}''
        {% endfor %}
    {% endif %}
    GROUP BY action'

sql: 'SELECT action, count(*) as times
    FROM logs
    {{ '{% if' }} filter_values(''action_type'')|length {{ '%}' }}
        WHERE action is null
        {{ '{% for' }} action in filter_values(''action_type'') {{ '%}' }}
            or action = ''{{ '{{' }} action {{ '}}' }}''
        {{ '{% endfor %}' }}
    {{ '{% endif %}' }}
    GROUP BY action'

与 dbt 同步

CLI 还允许您从 dbt 项目同步模型和指标。

如果您使用 dbt Core，您可以指定 CLI 到您的编译清单和配置文件，这样就会自动创建数据库，以及所有模型和指标。完整命令是

% preset-cli --workspaces=https://abcdef12.us1a.app.preset.io/ \
> superset sync dbt-core /path/to/dbt/my_project/target/manifest.json \
> --project=my_project --target=dev --profiles=${HOME}/.dbt/profiles.yml \
> --exposures=/path/to/dbt/my_project/models/exposures.yaml \
> --import-db \
> --external-url-prefix=http://localhost:8080/

运行此命令将

1. 读取 dbt 配置文件并在预设工作区中为指定项目创建 $target 数据库。

2. 项目中的每个来源都将创建为预设工作区中的数据集。

3. 项目中的每个模型都将创建为预设工作区中的数据集。

4. 任何 指标 都将添加到相应的数据集中。

5. 在 dbt 源和/或模型之上构建的每个仪表板都将同步回 dbt，作为一个 暴露。

描述、标签和其他元数据也将从 dbt 模型同步到数据集的相应字段。还可以直接在模型定义下指定仅适用于 Superset 的字段的值，在 model.meta.superset.{{field_name}} 下。例如，要指定数据集的缓存超时

models:
  - name: my_dbt_model
    meta:
      superset:
        cache_timeout: 250 # Setting the dataset cache timeout to 250.

对于指标也是如此。例如，要指定指标的 d3 格式

- name: avg_revenue
  label: "AVG Revenue"
  model: ref('my_dbt_model')
  calculation_method: average
  expression: price_each
  timestamp: date
  meta:
    superset:
      d3format: '%d'

--external-url-prefix 应指向您的 dbt 文档，以便工作区中的资源可以指向它们被管理的真实来源。与原生同步类似，dbt 同步也支持 --disallow-edits 标志。

默认情况下，CLI 同步会在目标工作区使用以下名称结构创建一个新数据库

f"{project_name}_{target_name}"

如果您想将数据同步到工作区上的现有数据库连接，您可以在配置文件中的 <target-name> 下指定数据库连接名称

meta:
  superset:
    database_name: my DB name # <= specify the database connection/display name used on the workspace

示例

jaffle_shop:
  outputs:
    dev:
      meta:
        superset:
          database_name: Postgres - Production

如果传递了 --import-db 并且在工作区上找到了数据库连接，则操作会使用 dbt 连接设置更新连接配置。

如果您正在使用 dbt Cloud，您还可以通过传递一个作业 ID 和一个 服务账户访问令牌 来代替。

% preset-cli --workspaces=https://abcdef12.us1a.app.preset.io/ \
> superset sync dbt-cloud \
> $TOKEN $JOB_ID \
> --external-url-prefix=http://localhost:8080/

令牌只需要访问您项目中的“仅元数据”权限集。您可以通过访问 dbt Cloud 中的项目 URL 并查看 URL 中的最后一个 ID 来查看作业 ID。例如，如果 URL 是 https://cloud.getdbt.com/#/accounts/12345/projects/567890/jobs/，则作业 ID 为 567890。

从 dbt Cloud 同步时，数据库连接必须在目标工作区中已经存在。工作区上的连接显示名称必须与 dbt Cloud 中的数据库名称匹配。

% preset-cli ... --select my_model    # sync only "my_model"
% preset-cli ... --select my_model+   # sync "my_model" and its children
% preset-cli ... --select my_model+2  # sync "my_model" and its children up to 2 degrees
% preset-cli ... --select +my_model   # sync "my_model" and its parents
% preset-cli ... --select +my_model+  # sync "my_model" with parents and children

% preset-cli ... --select my_model --select my_other_model

% preset-cli ... --select my_model+,tag:test

% preset-cli --select my_model+ --exclude tag:test

导出资源

CLI 还可以用来从给定的预设工作区（使用 preset-cli）或 Superset 实例（使用 superset-cli）导出资源（数据库、数据集、图表和仪表板）。这对于在工作区之间迁移资源、从现有的 Superset 安装迁移到 Preset，甚至从 Preset 迁移到 Superset（Preset 的一个优点是无需供应商锁定！）非常有用。

要从自托管 Superset 实例导出资源

% superset-cli https://superset.example.org/ export /path/to/directory

这将在 /path/to/directory 中创建一个漂亮的目录结构，准备好使用 sync native 命令导入。

要从预设工作区导出资源

% preset-cli --workspaces=https://abcdef12.us1a.app.preset.io/ \
> superset export /path/to/directory

还可以使用 CLI 导出特定资源

使用 --asset-type 来导出给定类型的所有资产。可用选项

• 仪表板

• 图表

• 数据集

• 数据库

例如，运行以下命令将导出此工作区中的所有仪表板（不会包括数据集、图表和数据库连接）

% preset-cli --workspaces=https://abcdef12.us1a.app.preset.io/ \
> superset export /path/to/directory --asset-type=dashboard

使用 --asset-ids 来过滤特定资产。可用选项

• 仪表板-ids

• 图表-ids

• 数据集-ids

• 数据库-ids

例如，运行以下命令将从这个工作区中导出指定的仪表板（包括数据集、图表和数据库连接）

% preset-cli --workspaces=https://abcdef12.us1a.app.preset.io/ \
> superset export /path/to/directory --dashboard-ids=9,10

要将导出的资源导入到预设工作区中

% preset-cli --workspaces=https://abcdef12.us1a.app.preset.io/ \
> superset sync native /path/to/directory

最后，要将资源导入到独立的 Superset 实例中

% superset-cli https://superset.example.org/ sync native /path/to/directory

请注意，任何现有的 Jinja2 模板标记都将被转义。例如，如果您有一个定义为

SELECT action, count(*) as times
FROM logs
WHERE
    action in {{ filter_values('action_type')|where_in }}
GROUP BY action

的虚拟数据集

SELECT action, count(*) as times
FROM logs
WHERE
    action in {{ '{{' }} filter_values('action_type')|where_in }} '}}' }}
GROUP BY action

生成的 YAML 文件将具有以下查询定义