Zillion: 智能数据建模与分析的强大工具

Zillion简介

Zillion是一款强大的数据建模和分析工具,它允许通过简单的API将多个数据源的数据结合起来进行分析。Zillion在您的数据之上充当语义层,为您编写SQL,并可以轻松地与现有的数据库基础设施集成。Zillion的NLP扩展还提供了实验性的AI支持的自然语言查询和仓库配置功能。

使用Zillion,您可以:

• 定义包含各种SQL和/或文件数据源的数据仓库
• 定义或反映数据中的指标、维度和关系
• 运行多数据源报告并将结果合并到DataFrame中
• 灵活地使用多级汇总和表格透视来聚合数据
• 使用公式自定义或组合字段
• 应用技术转换,包括滚动、累积和排名统计
• 应用自动类型转换 - 例如,从"日期"列中获得免费的"年份"维度
• 保存和共享报告规范
• 利用临时或公共数据源、表格和字段来丰富报告
• 使用自然语言查询您的数据仓库(NLP扩展)
• 利用AI来引导您的仓库配置(NLP扩展)

安装

警告: 该项目处于alpha状态,可能会发生变化。请仔细测试生产使用并报告任何问题。

$ pip install zillion

或

$ pip install zillion[nlp]

Zillion基础知识

以下内容旨在快速概述Zillion中用于数据仓库的一些理论和术语,这对于该领域的新手来说会很有用。

简而言之:Zillion为您编写SQL,并通过非常简单的API使数据可访问:

result = warehouse.execute(
    metrics=["revenue", "leads"],
    dimensions=["date"],
    criteria=[
        ("date", ">", "2020-01-01"),
        ("partner", "=", "Partner A")
    ]
)

指标和维度

在Zillion中,报告请求中使用的主要有两种类型的字段:

1. 维度:用于标记、分组和过滤的数据属性
2. 指标:可以沿维度分解的事实和度量

字段封装了数据中列的概念。例如,您可能有一个名为"revenue"的字段。该字段可能出现在多个数据源中,或者可能出现在单个数据源内的多个表中。Zillion理解所有这些列代表相同的概念,它可以尝试使用其中任何一个来满足请求"revenue"的报告。

同样,用于构建仓库的主要有两种类型的表:

1. 维度表:仅包含相关维度的参考/属性表
2. 指标表:可能包含指标和一些相关维度/属性的事实表

维度表通常在行数方面是静态的或缓慢增长的,并且包含与主键相关的属性。一些常见的例子是美国邮政编码列表或公司/合作伙伴目录。

指标表通常更具事务性。一些常见的例子是Web请求记录、电子商务销售或股票市场价格历史。

仓库理论

如果您真的想深入了解Zillion采用的维度建模和钻取查询技术,我建议阅读Ralph Kimball关于数据仓库的书。

总之,钻取查询形成一个或多个查询,以满足对可能存在于多个数据源和/或表中特定维度粒度的指标的报告请求。

Zillion支持灵活的仓库设置,如雪花模式或星型模式,尽管它并不挑剔。您可以通过父子血统指定表关系,Zillion还可以根据维度表主键的存在推断可接受的连接。Zillion目前不支持多对多关系,尽管大多数面向分析的场景应该能够通过在模型中添加视图来解决这个问题。

查询层

Zillion报告可以被认为在两个层次上运行:

1. 数据源层:针对仓库数据源的SQL查询
2. 组合层:针对数据源层组合数据的最终SQL查询

组合层只是另一个SQL数据库(默认为内存中的SQLite),用于将数据源数据联系在一起,并应用一些其他功能,如汇总、行过滤、行限制、排序、透视和技术计算。

仓库创建

有多种方法可以从本地或远程文件快速初始化仓库:

# 路径/链接到CSV、XLSX、XLS、JSON、HTML或Google表格
# 这将构建一个单表仓库,用于快速/临时分析。
url = "https://raw.githubusercontent.com/totalhack/zillion/master/tests/dma_zip.xlsx"
wh = Warehouse.from_data_file(url, ["Zip_Code"]) # 第二个参数是主键

# 路径/链接到sqlite数据库
# 这可以构建单表或多表仓库
url = "https://github.com/totalhack/zillion/blob/master/tests/testdb1?raw=true"
wh = Warehouse.from_db_file(url)

# 路径/链接到WarehouseConfigSchema(或传递dict)
# 这是推荐的生产方法!
config = "https://raw.githubusercontent.com/totalhack/zillion/master/examples/example_wh_config.json"
wh = Warehouse(config=config)

Zillion还提供了一个辅助脚本来为现有数据库引导DataSource配置文件。请参阅zillion.scripts.bootstrap_datasource_config.py。引导脚本需要连接/数据库url和输出文件作为参数。有关更多选项,请参阅--help输出,包括可选的--nlp标志,该标志利用OpenAI推断配置信息,如列类型、表类型和表关系。NLP功能需要安装NLP扩展,并在您的Zillion配置文件中设置以下内容:

• OPENAI_MODEL
• OPENAI_API_KEY

执行报告

Zillion的主要目的是针对Warehouse执行报告。在高层次上,您将按照以下方式制作报告:

result = warehouse.execute(
    metrics=["revenue", "leads"],
    dimensions=["date"],
    criteria=[
        ("date", ">", "2020-01-01"),
        ("partner", "=", "Partner A")
    ]
)
print(result.df) # Pandas DataFrame

与编写SQL相比,将维度视为group by SQL语句的目标列会有所帮助。将指标视为您正在聚合的列。将条件视为where子句。您的条件在数据源层SQL查询中应用。

ReportResult有一个Pandas DataFrame,其中维度作为索引,指标作为列。

据说Report有一个粒度,它定义了每个指标必须能够加入的维度,以满足Report要求。粒度是所有维度的组合,包括在条件或指标公式中引用的维度。在上面的例子中,粒度将是{date, partner}。"revenue"和"leads"都必须能够加入这些维度,才能实现这个报告。

这些概念可能需要一些时间才能理解,显然会随着数据模型的具体情况而变化,但当您开始针对数据仓库制作报告时,您会变得更加熟悉它们。

自然语言查询

通过NLP扩展,Zillion对数据仓库的自然语言查询提供了实验性支持。例如:

result = warehouse.execute_text("revenue and leads by date last month")
print(result.df) # Pandas DataFrame

此NLP功能需要运行Qdrant(向量数据库)实例,并在Zillion配置文件中设置以下值:

• QDRANT_HOST
• OPENAI_API_KEY

嵌入将在Qdrant和本地缓存中生成和存储。向量数据库将在您首次尝试使用它时通过分析仓库中的所有字段进行初始化。在此repo的根目录中提供了运行Qdrant的示例docker文件。

您可以控制字段的嵌入方式。特别是在任何字段的配置中,您可以选择是否从嵌入中排除字段或覆盖哪些嵌入映射到该字段。默认情况下,包括所有字段。以下示例将从嵌入中排除net_revenue字段,并将revenue指标请求映射到gross_revenue字段。

{
    "name": "gross_revenue",
    "type": "numeric(10,2)",
    "aggregation": "sum",
    "rounding": 2,
    "meta": {
        "nlp": {
            // enabled defaults to true
            "embedding_text": "revenue" // str or list of str
        }
    }
},
{
    "name": "net_revenue",
    "type": "numeric(10,2)",
    "aggregation": "sum",
    "rounding": 2,
    "meta": {
        "nlp": {
            "enabled": false
        }
    }
},

此外,您还可以通过以下仓库级配置设置排除字段:

{
    "meta": {
        "nlp": {
            "field_disabled_patterns": [
                // list of regex patterns to exclude
                "rpl_ma_5"
            ],
            "field_disabled_groups": [
                // list of "groups" to exclude, assuming you have
                // set group value in the field's meta dict.
                "No NLP"
            ]
        }
    },
    ...
}

如果在上述任何级别禁用了字段,它将被忽略。随着数据模型变得更加复杂,当您想在可能混淆类似命名字段的情况下指导NLP逻辑时,这种类型的控制会变得有用。每当您调整要排除的字段时,您都需要使用Warehouse.init_embeddings上的force_recreate标志强制重新创建嵌入集合。

注意: 这个功能还处于初级阶段。它的有用性将取决于输入查询和数据模型(即良好的字段名称)的质量!

Zillion配置

除了配置Warehouse的结构(将在下面进一步讨论)之外,Zillion还有一个全局配置来控制一些基本设置。ZILLION_CONFIG环境变量可以指向yaml配置文件。有关可以设置的值的更多详细信息,请参阅examples/sample_config.yaml。以ZILLION_前缀的环境变量可以覆盖配置设置(即ZILLION_DB_URL将覆盖DB_URL)。

用于存储Zillion报告规范的数据库可以通过在Zillion配置中将DB_URL值设置为有效的数据库连接字符串来配置。默认情况下,使用/tmp中的SQLite数据库。

示例 - 销售分析

下面我们将介绍一个简单的假设销售数据模型,演示基本的DataSource和Warehouse配置,然后展示一些示例报告。数据是Zillion测试代码的一部分的简单SQLite数据库。作为参考,架构如下:

CREATE TABLE partners (
  id INTEGER PRIMARY KEY,
  name VARCHAR NOT NULL UNIQUE,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE campaigns (
  id INTEGER PRIMARY KEY,
  name VARCHAR NOT NULL UNIQUE,
  category VARCHAR NOT NULL,
  partner_id INTEGER NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE leads (
  id INTEGER PRIMARY KEY,
  name VARCHAR NOT NULL,
  campaign_id INTEGER NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE sales (
  id INTEGER PRIMARY KEY,
  item VARCHAR NOT NULL,
  quantity INTEGER NOT NULL,
  revenue DECIMAL(10, 2),
  lead_id INTEGER NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

仓库配置

可以从定义其字段、数据源和表的JSON或YAML配置创建Warehouse。下面的代码显示了如何在一行代码中完成,如果您有指向JSON/YAML Warehouse配置的指针:

from zillion import Warehouse

wh = Warehouse(config="https://raw.githubusercontent.com/totalhack/zillion/master/examples/example_wh_config.json")

此示例配置在其DataSource connect信息中使用data_url,告诉Zillion动态下载该数据并将其连接为SQLite数据库。这对于快速示例或分析很有用,尽管在大