recap

<div align="center"> <img src="https://yellow-cdn.veclightyear.com/0a4dffa0/33fdf89c-474c-4bc0-8b73-14237a477bb9.png?raw=true" alt="recap"> </div>

什么是Recap？

Recap以标准格式从Web服务、数据库和模式注册表中读取和写入模式。

⭐️ 如果你喜欢这个项目，请给它一个星标！这有助于项目获得更多关注。

目录

• 什么是Recap？
• 支持的格式
• 安装
• 使用方法
  • 命令行界面
  • 网关
  • 注册表
  • API
  • Docker
• 模式
• 文档

支持的格式

格式	读取	写入
Avro	✅	✅
BigQuery	✅
Confluent模式注册表	✅
Hive元数据存储	✅
JSON模式	✅	✅
MySQL	✅
PostgreSQL	✅
Protobuf	✅	✅
Snowflake	✅
SQLite	✅

安装

安装Recap及其所有可选依赖项：

pip install 'recap-core[all]'

你也可以选择特定的依赖项：

pip install 'recap-core[avro,kafka]'

查看pyproject.toml获取可选依赖项列表。

使用方法

命令行界面

Recap配备了一个命令行界面，可以列出和读取外部系统的模式。

列出URL的子项：

recap ls postgresql://user:pass@host:port/testdb

[
  "pg_toast",
  "pg_catalog",
  "public",
  "information_schema"
]

继续深入：

recap ls postgresql://user:pass@host:port/testdb/public

[
  "test_types"
]

以Recap结构形式读取test_types表的模式：

recap schema postgresql://user:pass@host:port/testdb/public/test_types

{
  "type": "struct",
  "fields": [
    {
      "type": "int64",
      "name": "test_bigint",
      "optional": true
    }
  ]
}

网关

Recap配备了一个无状态的HTTP/JSON网关，可以列出和读取数据目录和数据库中的模式。

在http://localhost:8000启动服务器：

recap serve

列出PostgreSQL数据库中的模式：

curl http://localhost:8000/gateway/ls/postgresql://user:pass@host:port/testdb

["pg_toast","pg_catalog","public","information_schema"]

读取模式：

curl http://localhost:8000/gateway/schema/postgresql://user:pass@host:port/testdb/public/test_types

{"type":"struct","fields":[{"type":"int64","name":"test_bigint","optional":true}]}

网关实时从外部系统获取模式，并以Recap模式的形式返回。

OpenAPI模式可在http://localhost:8000/docs获取。

注册表

你可以在Recap的模式注册表中存储模式。

在http://localhost:8000启动服务器：

recap serve

将模式放入注册表：

curl -X POST \
    -H "Content-Type: application/x-recap+json" \
    -d '{"type":"struct","fields":[{"type":"int64","name":"test_bigint","optional":true}]}' \
    http://localhost:8000/registry/some_schema

从注册表获取模式（及版本）：

curl http://localhost:8000/registry/some_schema

[{"type":"struct","fields":[{"type":"int64","name":"test_bigint","optional":true}]},1]

将模式的新版本放入注册表：

curl -X POST \
    -H "Content-Type: application/x-recap+json" \
    -d '{"type":"struct","fields":[{"type":"int32","name":"test_int","optional":true}]}' \
    http://localhost:8000/registry/some_schema

列出架构版本：

curl http://localhost:8000/registry/some_schema/versions

[1,2]

获取架构的特定版本：

curl http://localhost:8000/registry/some_schema/versions/1

[{"type":"struct","fields":[{"type":"int64","name":"test_bigint","optional":true}]},1]

注册表使用fsspec将架构存储在各种文件系统中，如S3、GCS、ABS和本地文件系统。更多详情请参见注册表文档。

OpenAPI架构可在http://localhost:8000/docs获取。

API

Recap有recap.converters和recap.clients包。

• 转换器用于将架构转换为Recap架构或从Recap架构转换。
• 客户端从外部系统（数据库、架构注册表等）读取架构，并使用转换器返回Recap架构。

从PostgreSQL读取架构：

from recap.clients import create_client

with create_client("postgresql://user:pass@host:port/testdb") as c:
    c.schema("testdb", "public", "test_types")

将架构转换为Avro、Protobuf和JSON架构：

from recap.converters.avro import AvroConverter
from recap.converters.protobuf import ProtobufConverter
from recap.converters.json_schema import JSONSchemaConverter

avro_schema = AvroConverter().from_recap(struct)
protobuf_schema = ProtobufConverter().from_recap(struct)
json_schema = JSONSchemaConverter().from_recap(struct)

将架构从一种格式转换为另一种格式：

from recap.converters.json_schema import JSONSchemaConverter
from recap.converters.avro import AvroConverter

json_schema = """
{
    "type": "object",
    "$id": "https://recap.build/person.schema.json",
    "properties": {
        "name": {"type": "string"}
    }
}
"""

# 使用Recap作为中间格式将JSON架构转换为Avro
struct = JSONSchemaConverter().to_recap(json_schema)
avro_schema = AvroConverter().from_recap(struct)

在Recap的架构注册表中存储架构：

from recap.storage.registry import RegistryStorage
from recap.types import StructType, IntType

storage = RegistryStorage("file:///tmp/recap-registry-storage")
version = storage.put(
    "postgresql://localhost:5432/testdb/public/test_table",
    StructType(fields=[IntType(32)])
)
storage.get("postgresql://localhost:5432/testdb/public/test_table")

# 获取架构的所有版本
versions = storage.versions("postgresql://localhost:5432/testdb/public/test_table")

# 列出注册表中的所有架构
schemas = storage.ls()

Docker

Recap的网关和注册表也可作为Docker镜像使用：

docker run \
    -p 8000:8000 \
    -e RECAP_URLS=["postgresql://user:pass@localhost:5432/testdb"]' \
    ghcr.io/recap-build/recap:latest

更多详情请参见Recap的Docker文档。

架构

有关Recap类型系统的详细信息，请参阅Recap的类型规范。

文档

Recap的文档可在recap.build获取。