Delta Sharing：安全数据共享的开放协议

Delta Sharing是一个用于安全实时交换大型数据集的开放协议，使组织能够实时共享数据，无论他们使用何种计算平台。这是一个简单的REST协议，可以安全地共享云数据集的一部分访问权限，并利用现代云存储系统（如S3、ADLS或GCS）可靠地传输数据。

使用Delta Sharing，访问共享数据的用户可以通过pandas、Tableau、Apache Spark、Rust或其他支持该开放协议的系统直接连接到数据，而无需首先部署特定的计算平台。数据提供者可以一次性共享数据集以覆盖广泛的消费者，而消费者可以在几分钟内开始使用数据。

这个仓库包含以下组件：

Delta Sharing协议规范。
Python连接器：一个实现Delta Sharing协议的Python库，用于将共享表读取为pandasDataFrame或Apache Spark DataFrame。
Apache Spark连接器：一个实现Delta Sharing协议的Apache Spark连接器，用于从Delta Sharing服务器读取共享表。这些表可以在SQL、Python、Java、Scala或R中访问。
Delta Sharing服务器：一个用于开发目的的Delta Sharing协议参考实现服务器。用户可以部署此服务器来共享现代云存储系统上Delta Lake和Apache Parquet格式的现有表。

Python连接器

Delta Sharing Python连接器是一个实现Delta Sharing协议的Python库，用于从Delta Sharing服务器读取表。您可以将共享表加载为pandas DataFrame，或者如果在安装了Apache Spark连接器的PySpark中运行，则可以加载为Apache Spark DataFrame。

系统要求

delta-sharing 1.1+版本需要Python 3.8+，旧版本需要Python 3.6+ 如果运行Linux，glibc版本 >= 2.31（用于自动安装delta-kernel-rust-sharing-wrapper包，更多详情请参见下一节）

安装

pip3 install delta-sharing

如果您使用的是Databricks Runtime，可以按照Databricks库文档在集群上安装该库。

如果由于下载delta-kernel-rust-sharing-wrapper出现问题而无法安装，请尝试以下操作：

检查python3版本是否 >= 3.8
将pip3升级到最新版本
检查linux glibc版本是否 >= 2.31

如果您无法升级glibc或您的操作系统不被delta-kernel-rust-sharing-wrapper pypi安装支持，您需要手动安装该包。请查看https://pypi.org/project/delta-kernel-rust-sharing-wrapper/0.1.0/#files以了解支持的操作系统。

要手动安装delta-kernel-rust-sharing-wrapper包：

# 您需要使用较旧版本的delta-sharing包，该版本未将delta-kernel-rust-sharing-wrapper集成到安装中
pip3 install delta-sharing==1.1.0 

cd [delta-sharing-root]/python/delta-kernel-rust-sharing-wrapper
python3 -m venv .venv
source .venv/bin/activate
pip3 install maturin
maturin develop

访问共享数据

连接器根据配置文件访问共享表，这些配置文件是包含用户访问Delta Sharing服务器凭据的JSON文件。我们有几种入门方式：

下载配置文件以访问我们托管的开放、示例Delta Sharing服务器这里。您可以使用这个样本数据试用连接器。
启动您自己的Delta Sharing服务器并按照配置文件格式创建您自己的配置文件以连接到此服务器。
从您的数据提供者下载配置文件。

快速入门

保存配置文件后，您可以在连接器中使用它来访问共享表。

import delta_sharing

# 指向配置文件。它可以是本地文件系统上的文件或远程存储上的文件。
profile_file = "<profile-file-path>"

# 创建一个SharingClient。
client = delta_sharing.SharingClient(profile_file)

# 列出所有共享表。
client.list_all_tables()

# 创建一个访问共享表的URL。
# 表路径是配置文件路径后跟"#"和表的完全限定名称（`<share-name>.<schema-name>.<table-name>`）。
table_url = profile_file + "#<share-name>.<schema-name>.<table-name>"

# 从表中获取10行并将其转换为Pandas DataFrame。这可用于从无法完全装入内存的表中读取样本数据。
delta_sharing.load_as_pandas(table_url, limit=10)

# 将表加载为Pandas DataFrame。这可用于处理可以装入内存的表。
delta_sharing.load_as_pandas(table_url)

# 显式使用Delta格式将表加载为Pandas DataFrame
delta_sharing.load_as_pandas(table_url, use_delta_format = True)

# 如果代码在PySpark中运行，您可以使用`load_as_spark`将表加载为Spark DataFrame。
delta_sharing.load_as_spark(table_url)

如果表支持历史共享（在开源Delta Sharing服务器中tableConfig.cdfEnabled=true），连接器可以查询表的变更。

# 加载从版本0到版本5的表变更，作为Pandas DataFrame。
delta_sharing.load_table_changes_as_pandas(table_url, starting_version=0, ending_version=5)

# 如果代码在PySpark中运行，您可以将表变更加载为Spark DataFrame。
delta_sharing.load_table_changes_as_spark(table_url, starting_version=0, ending_version=5)

您可以通过运行我们的示例并使用开放、示例Delta Sharing服务器来尝试这些操作。

关于配置文件路径的详细信息

SharingClient 和 load_as_pandas 的配置文件路径可以是 FSSPEC 支持的任何 URL(例如 s3a://my_bucket/my/profile/file)。如果您使用 Databricks 文件系统，还可以在路径前加上 /dbfs/ 来像访问本地文件一样访问配置文件。
load_as_spark 的配置文件路径可以是 Hadoop 文件系统支持的任何 URL(例如 s3a://my_bucket/my/profile/file)。
表路径是配置文件路径后跟 # 和表的完全限定名(<共享名称>.<模式名称>.<表名称>)。

Apache Spark 连接器

Apache Spark 连接器实现了 Delta Sharing 协议，用于从 Delta Sharing 服务器读取共享表。它可以在 SQL、Python、Java、Scala 和 R 中使用。

系统要求

Java 8+
Scala 2.12.x
Apache Spark 3+ 或 Databricks Runtime 9+

访问共享数据

连接器从配置文件加载用户凭据。请参阅访问共享数据下载我们示例服务器或您自己的数据共享服务器的配置文件。

配置 Apache Spark

您可以通过以下两种方式设置 Apache Spark 以加载 Delta Sharing 连接器：

交互式运行：使用 Delta Sharing 连接器启动 Spark shell(Scala 或 Python)，并在 shell 中交互式运行代码片段。
作为项目运行：用 Delta Sharing 连接器设置 Maven 或 SBT 项目(Scala 或 Java)，将代码片段复制到源文件中，然后运行项目。

如果您使用 Databricks Runtime，可以跳过本节，按照 Databricks Libraries 文档在集群上安装连接器。

设置交互式 shell

要在 Spark 的 Scala/Python shell 中交互式地使用 Delta Sharing 连接器，可以按如下方式启动 shell。

PySpark shell

pyspark --packages io.delta:delta-sharing-spark_2.12:3.1.0

Scala Shell

bin/spark-shell --packages io.delta:delta-sharing-spark_2.12:3.1.0

设置独立项目

如果您想使用 Maven Central Repository 中的 Delta Sharing 连接器构建 Java/Scala 项目，可以使用以下 Maven 坐标。

Maven

您可以通过在 POM 文件中添加它作为依赖项来在 Maven 项目中包含 Delta Sharing 连接器。Delta Sharing 连接器使用 Scala 2.12 编译。

<dependency>
  <groupId>io.delta</groupId>
  <artifactId>delta-sharing-spark_2.12</artifactId>
  <version>3.1.0</version>
</dependency>

SBT

您可以通过在 build.sbt 文件中添加以下行来在 SBT 项目中包含 Delta Sharing 连接器：

libraryDependencies += "io.delta" %% "delta-sharing-spark" % "3.1.0"

快速入门

保存配置文件并使用连接器库启动 Spark 后，您可以使用任何语言访问共享表。

SQL

-- 表路径是配置文件路径后跟 `#` 和表的完全限定名
-- (`<共享名称>.<模式名称>.<表名称>`)。
CREATE TABLE mytable USING deltaSharing LOCATION '<配置文件路径>#<共享名称>.<模式名称>.<表名称>';
SELECT * FROM mytable;

Python

# 表路径是配置文件路径后跟 `#` 和表的完全限定名
# (`<共享名称>.<模式名称>.<表名称>`)。
table_path = "<配置文件路径>#<共享名称>.<模式名称>.<表名称>"
df = spark.read.format("deltaSharing").load(table_path)

Scala

// 表路径是配置文件路径后跟 `#` 和表的完全限定名
// (`<共享名称>.<模式名称>.<表名称>`)。
val tablePath = "<配置文件路径>#<共享名称>.<模式名称>.<表名称>"
val df = spark.read.format("deltaSharing").load(tablePath)

Java

// 表路径是配置文件路径后跟 `#` 和表的完全限定名
// (`<共享名称>.<模式名称>.<表名称>`)。
String tablePath = "<配置文件路径>#<共享名称>.<模式名称>.<表名称>";
Dataset<Row> df = spark.read.format("deltaSharing").load(tablePath);

R

# 表路径是配置文件路径后跟 `#` 和表的完全限定名
# (`<共享名称>.<模式名称>.<表名称>`)。
table_path <- "<配置文件路径>#<共享名称>.<模式名称>.<表名称>"
df <- read.df(table_path, "deltaSharing")

您可以通过运行我们的示例来尝试使用开放的示例 Delta Sharing 服务器。

CDF

从 0.5.0 版本开始，Delta Sharing 支持查询变更数据流。一旦提供者在原始 delta 表上启用 CDF 并通过 Delta Sharing 共享它，接收者就可以像查询 delta 表的 CDF 一样查询 Delta Sharing 表的 CDF。

val tablePath = "<配置文件路径>#<共享名称>.<模式名称>.<表名称>"
val df = spark.read.format("deltaSharing")
  .option("readChangeFeed", "true")
  .option("startingVersion", "3")
  .load(tablePath)

流式处理

从 0.6.0 版本开始，Delta Sharing 表可以用作 Spark 结构化流的数据源。一旦提供者共享带有历史记录的表，接收者就可以对该表执行流式查询。

注意：Delta Sharing 流式处理不支持 Trigger.AvailableNow，因为它从 Spark 3.3.0 开始支持，而 Delta Sharing 仍在使用 Spark 3.1.1。

val tablePath = "<配置文件路径>#<共享名称>.<模式名称>.<表名称>"
val df = spark.readStream.format("deltaSharing")
  .option("startingVersion", "1")
  .option("skipChangeCommits", "true")
  .load(tablePath)

表路径

配置文件路径可以是 Hadoop 文件系统支持的任何 URL(例如 s3a://my_bucket/my/profile/file)。
表路径是配置文件路径后跟 # 和表的完全限定名(<共享名称>.<模式名称>.<表名称>)。

社区

<div align="center"> <img src="https://yellow-cdn.veclightyear.com/835a84d5/2ccfb63a-bd99-4f97-9a1a-8d71d4c3fc06.png" alt="Delta Sharing OSS 连接器" width="400" /> </div> <table> <tr> <th>连接器</th> <th>链接</th> <th>状态</th> <th>支持的功能</th> </tr> <tr> <td>Power BI</td> <td>Databricks 拥有</td> <td>已发布</td> <td>QueryTableVersion<br>QueryTableMetadata<br>QueryTableLatestSnapshot</td> </tr> <tr> <td>Clojure</td> <td>

amperity/delta-sharing-client-clj

</td> <td>已发布</td> <td>QueryTableVersion<br>QueryTableMetadata<br>QueryTableLatestSnapshot<br>QueryTableChanges(CDF)<br>时间旅行查询<br>查询版本之间的变更<br>Delta 格式查询<br>限制和谓词下推</td> </tr> <tr> <tr> <td>Node.js</td> <td> [goodwillpunning/nodejs-sharing-client](https://github.com/goodwillpunning/nodejs-sharing-client) </td> <td>已发布</td> <td>QueryTableVersion<br>QueryTableMetadata<br>QueryTableLatestSnapshot</td> </tr> <tr> <td>Java</td> <td>

databrickslabs/delta-sharing-java-connector

</td> <td>已发布</td> <td>QueryTableVersion<br>QueryTableMetadata<br>QueryTableLatestSnapshot</td> </tr> <tr> <td>Arcuate</td> <td>

databrickslabs/arcuate

</td> <td>已发布</td> <td>QueryTableVersion<br>QueryTableMetadata<br>QueryTableLatestSnapshot</td> </tr> <tr> <td>Rust</td> <td>

r3stl355/delta-sharing-rust-client

</td> <td>已发布</td> <td>QueryTableVersion<br>QueryTableMetadata<br>QueryTableLatestSnapshot</td> </tr> <tr> <td>Go</td> <td>

magpierre/delta-sharing

</td> <td>已发布</td> <td>QueryTableVersion<br>QueryTableMetadata<br>QueryTableLatestSnapshot</td> </tr> <tr> <td>C++</td> <td>

magpierre/delta-sharing

</td> <td>已发布</td> <td>QueryTableMetadata<br>QueryTableLatestSnapshot</td> </tr> <tr> <td>R</td> <td>

zacdav-db/delta-sharing-r

</td> <td>已发布</td> <td>QueryTableVersion<br>QueryTableMetadata<br>QueryTableLatestSnapshot</td> </tr> <tr> <td>Google电子表格</td> <td>

delta-incubator/delta-sharing-connectors

</td> <td>测试版</td> <td>QueryTableVersion<br>QueryTableMetadata<br>QueryTableLatestSnapshot</td> </tr> <tr> <td>Airflow</td> <td>

apache/airflow

</td> <td>未发布</td> <td>不适用</td> </tr> <tr> <td>Excel-Connector</td> <td>

https://www.exponam.com/solutions/

</td> <td>限量发布</td> <td>不适用</td> </tr> <tr> <td>Lakehouse Sharing</td> <td>

rajagurunath/lakehouse-sharing

</td> <td>预览版</td> <td>

演示了一个与表格格式无关的数据共享<br/> 服务器（基于delta-sharing协议），用Python实现，同时支持Delta Lake和Iceberg格式。

</td> </tr> </table>

Delta Sharing参考服务器

Delta Sharing参考服务器是Delta Sharing协议的参考实现服务器。这可以用来设置一个小型服务来测试您自己实现Delta Sharing协议的连接器。请注意，这不是一个完整的安全Web服务器实现。如果您想将其公开，我们强烈建议您将其放在安全代理后面。

一些供应商也提供Delta Sharing的托管服务（例如，Databricks）。请参阅您的供应商网站了解如何在那里设置共享。有兴趣被列为服务提供商的供应商应在GitHub上开启一个问题，以便添加到此README和我们项目的网站中。

以下是设置参考服务器以共享您自己的数据的步骤。

获取预构建包

从GitHub Releases下载预构建包delta-sharing-server-x.y.z.zip。

服务器配置和添加共享数据

解压预构建包并复制服务器配置模板文件conf/delta-sharing-server.yaml.template以创建您自己的服务器yaml文件，例如conf/delta-sharing-server.yaml。
对您的yaml文件进行更改。您可能还需要更新一些服务器配置以满足特殊要求。
要添加共享数据，请在此配置文件中添加您希望从此服务器共享的Delta Lake表的引用。

配置服务器以访问云存储上的表

我们支持在S3、Azure Blob Storage和Azure Data Lake Storage Gen2上共享Delta Lake表。

S3

服务器使用hadoop-aws访问S3。服务器配置文件中的表路径应使用s3a://路径而不是s3://路径。有多种方法可以配置S3身份验证。

EC2 IAM元数据身份验证（推荐）

在EC2中运行的应用程序可以将IAM角色与VM关联，并查询EC2实例元数据服务以获取访问S3的凭证。

通过AWS环境变量进行身份验证

我们支持通过标准AWS环境变量进行配置。核心环境变量用于访问密钥和相关的秘密：

export AWS_ACCESS_KEY_ID=my.aws.key
export AWS_SECRET_ACCESS_KEY=my.secret.key

其他S3身份验证方法

您可以在hadoop-aws文档中找到其他方法。

Azure Blob Storage

服务器使用hadoop-azure读取Azure Blob Storage。使用Azure Blob Storage需要配置凭证。您可以创建一个名为core-site.xml的Hadoop配置文件，并将其添加到服务器的conf目录中。然后将以下内容添加到xml文件中：

<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="configuration.xsl"?>
<configuration>
  <property>
    <name>fs.azure.account.key.YOUR-ACCOUNT-NAME.blob.core.windows.net</name>
    <value>YOUR-ACCOUNT-KEY</value>
  </property>
</configuration>

YOUR-ACCOUNT-NAME是您的Azure存储帐户，YOUR-ACCOUNT-KEY是您的帐户密钥。

Azure Data Lake Storage Gen2

服务器使用hadoop-azure读取Azure Data Lake Storage Gen2。我们支持共享密钥身份验证。您可以创建一个名为core-site.xml的Hadoop配置文件，并将其添加到服务器的conf目录中。然后将以下内容添加到xml文件中：

<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="configuration.xsl"?>
<configuration>
  <property>
    <name>fs.azure.account.auth.type.YOUR-ACCOUNT-NAME.dfs.core.windows.net</name>
    <value>SharedKey</value>
    <description>
    </description>
  </property>
  <property>
    <name>fs.azure.account.key.YOUR-ACCOUNT-NAME.dfs.core.windows.net</name>
    <value>YOUR-ACCOUNT-KEY</value>
    <description>
    密码。切勿共享这些信息。
    </description>
  </property>
</configuration>

YOUR-ACCOUNT-NAME是您的Azure存储帐户，YOUR-ACCOUNT-KEY是您的帐户密钥。

Google Cloud Storage

我们支持使用服务帐户读取Google Cloud Storage。您可以在GCP身份验证文档中找到更多详细信息。要设置服务账户凭证，可以在启动 Delta Sharing 服务器之前指定 GOOGLE_APPLICATION_CREDENTIALS 环境变量。

export GOOGLE_APPLICATION_CREDENTIALS="密钥路径"

将"密钥路径"替换为包含您的服务账户密钥的 JSON 文件的路径。

Cloudflare R2

我们使用 R2 实现的 S3 API 和 hadoop-aws 来读取 Cloudflare R2。服务器配置文件中的表路径应使用 s3a:// 方案。您必须生成 API 令牌以便与现有的 S3 兼容 SDK 一起使用。这些凭证可以替代服务器 conf 目录中名为 core-site.xml 的 Hadoop 配置文件中的 S3 凭证。为了使 R2 正常工作，您还需要直接指定 S3 端点，并将 fs.s3a.paging.maximum 从 Hadoop 的默认值 5000 减少到 1000，因为 R2 只支持 MaxKeys <= 1000。

<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="configuration.xsl"?>
<configuration>
  <property>
    <name>fs.s3a.access.key</name>
    <value>您的访问密钥</value>
  </property>
  <property>
    <name>fs.s3a.secret.key</name>
    <value>您的密钥</value>
  </property>
  <property>
    <name>fs.s3a.endpoint</name>
    <value>https://您的账户ID.r2.cloudflarestorage.com</value>
  </property>
  <property>
    <name>fs.s3a.paging.maximum</name>
    <value>1000</value>
  </property>
</configuration>

将"您的访问密钥"替换为您生成的 API 令牌的 R2 访问密钥 ID，"您的密钥"替换为您生成的 API 令牌的秘密访问密钥，"您的账户ID"替换为您的 Cloudflare 账户 ID。

注意：S3 和 R2 凭证不能同时配置。

授权

服务器支持使用预配置的承载令牌进行基本授权。您可以在服务器的 yaml 文件中添加以下配置：

authorization:
  bearerToken: <令牌>

然后，任何请求都应该携带上述令牌发送，否则服务器将拒绝该请求。

如果您没有在服务器的 yaml 文件中配置承载令牌，所有请求将被接受，无需授权。

为了更安全，我们建议您将服务器置于安全代理（如 NGINX）后面，以设置 JWT 认证。

启动服务器

运行以下 shell 命令：

bin/delta-sharing-server -- --config <服务器配置yaml文件>

<服务器配置yaml文件> 应该是您在上一步创建的 yaml 文件的路径。您可以在 sbt-native-packager 中找到配置 JVM 的选项。

使用预构建的 Docker 镜像

您可以通过运行以下命令使用来自 https://hub.docker.com/r/deltaio/delta-sharing-server 的预构建 docker 镜像

docker run -p <主机端口>:<容器端口> \
  --mount type=bind,source=<服务器配置yaml文件>,target=/config/delta-sharing-server-config.yaml \
  deltaio/delta-sharing-server:0.7.8 -- --config /config/delta-sharing-server-config.yaml

注意，<容器端口> 应该与配置文件中定义的端口相同。

API 兼容性

Delta Sharing 服务器提供的 REST API 是稳定的公共 API。它们由 Delta Sharing 协议定义，我们将严格遵循整个协议。

Delta Sharing 服务器内部的接口不是公共 API。它们被视为内部接口，可能会在小版本/补丁版本之间发生变化。

Delta Sharing 协议

Delta Sharing 协议规范详细说明了该协议。

构建此项目

Python 连接器

要执行测试，请运行

python/dev/pytest

要以开发模式安装，请运行

cd python/
pip install -e .

要本地安装，请运行

cd python/
pip install .

要生成 wheel 文件，请运行

cd python/
python setup.py sdist bdist_wheel

它将生成 python/dist/delta_sharing-x.y.z-py3-none-any.whl。

Apache Spark 连接器和 Delta Sharing 服务器

Apache Spark 连接器和 Delta Sharing 服务器使用 SBT 进行编译。

要编译，请运行

build/sbt compile

要执行测试，请运行

build/sbt test

要生成 Apache Spark 连接器，请运行

build/sbt spark/package

它将生成 spark/target/scala-2.12/delta-sharing-spark_2.12-x.y.z.jar。

要生成预构建的 Delta Sharing 服务器包，请运行

build/sbt server/universal:packageBin

它将生成 server/target/universal/delta-sharing-server-x.y.z.zip。

要为 Delta Sharing 服务器构建 Docker 镜像，请运行

build/sbt server/docker:publishLocal

这将构建一个标记为 delta-sharing-server:x.y.z 的 Docker 镜像，您可以通过以下方式运行：

docker run -p <主机端口>:<容器端口> \
  --mount type=bind,source=<服务器配置yaml文件>,target=/config/delta-sharing-server-config.yaml \
  delta-sharing-server:x.y.z -- --config /config/delta-sharing-server-config.yaml

注意，<容器端口> 应该与配置文件中定义的端口相同。

有关更多命令，请参阅 SBT 文档。