Singer 学习十三 发现模式
发现模式
发现模式提供了一种描述tap 支持数据流的方式，使用了json schema 做为描述数据的结构以及每个数据流的
类型，发现模式的实现依赖tap 的数据源，有些taps 将硬编码每个流的模式，而其他的将连接到提供可用流的
描述的api，当运行发现模式时，tap 应该写如stdout 流列表，称为目录，每个条目包含关于流的一些基本信息和
描述流的json schema
发现模式下运行tap， 使用--discover
tap --config CONFIG --discover
我们可以在运行的时候将输出重定向到一个文件
tap --config CONFIG --discover > catalog.json
对于一些遗留的taps ，会使用properties.json 做为目录
schema
JSON用于表示数据，因为它无处不在，可读，并且特别适用于将数据公开为JSON（如Web API）的大量源。但是，
JSON远非完美：
- 它有一个有限类型的系统，不支持日期等常见类型，也没有整数和浮点数之间的区别
- 虽然它的灵活性使其易于使用，但它也可能导致兼容性问题
模式用于解决这些问题。一般而言，模式是描述数据结构的任何方式。模式由TEMA在SCHEMA消息中编写，格式遵循
JSON模式规范。
模式通过提供有关如何解释JSON基本类型的更多信息来解决有限的数据类型问题。例如，JSON Schema规范区分integer和number
类型，后者被适当地解释为浮点。此外，它定义了一个名为的字符串格式date-time，可用于指示数据点何时应为格式正确的时间戳字符串。
Schema提供了一种验证一组数据点结构的简便方法，从而减轻了JSON的兼容性问题。Taps通过鼓励每个流仅使用单个模式，并在持
久性之前根据其schema验证每个数据点来部署此概念。这迫使Tap作者思考如何解决模式演变和兼容性问题，将该责任尽可能接近原始数据源，
并使下游系统无需做出明智的假设来解决这些问题。
schema 是必需的，但它们可以用最广泛的术语定义 - “{}”的JSON schema 验证所有数据点。但是，Tap作者最好以尽可能窄的方式定义schema。
Stitch中的schema
Stitch Target和Stitch API使用schema如下：
- 当Stitch Target遇到未根据其流的最新schema验证的数据点时，它会失败
- schema必须是顶级的“对象”
- Stitch支持具有嵌套到任何深度的对象的schema，以及嵌套到任何深度的对象数组 - Stitch docs中的更多信息
- 在构造消息之前，必须完全解析并替换使用JSON模式$ref功能的引用SCHEMA。规范不支持传递额外schema以作为参考分辨率的方法。
- 类型string和格式的属性date-time将转换为目标数据库中的相应时间戳或日期时间类型
- 类型的属性integer在目标数据库中转换为整数
- 类型的属性number在目标数据库中转换为十进制或数字
（很快）maxLengthtype属性的参数string用于定义目标数据库中相应varchar列的宽度 - 当Stitch遇到与要在目标数据库中加载流的表不兼容的流的schema时，它会将数据添加到拒绝堆中
参考：
{
"type": [
"null",
"object"
],
"additionalProperties": false,
"properties": {
"id": {
"type": [
"null",
"string"
],
},
"name": {
"type": [
"null",
"string"
],
},
"date_modified": {
"type": [
"null",
"string"
],
"format": "date-time",
}
}
}
目录（catalog）
发现模式的输出应该是Tap支持的数据流列表。此JSON格式的列表称为目录。顶层是一个对象，其中一个被调用的键"streams"指向一个对象数组，
每个对象都有以下字段：
tap_stream_id 字符串 需要 流的唯一标识符。允许这与流的名称不同，以允许具有重复流名称的源。
schema 对象 需要 流的JSON模式。
table_name 字符串 可选的 对于数据库源，表的名称。
metadata 元数据数组 可选的 请参阅下面的元数据以获取解释
参考：
{
"streams": [
{
"tap_stream_id": "users",
"stream": "users",
"schema": {
"type": ["null", "object"],
"additionalProperties": false,
"properties": {
"id": {
"type": [
"null",
"string"
],
},
"name": {
"type": [
"null",
"string"
],
},
"date_modified": {
"type": [
"null",
"string"
],
"format": "date-time",
}
}
}
}
]
}
metadata
元数据是关联模式中节点的额外信息的首选机制。
应该通过tap 来写入和读取某些元数据。此元数据称为discoverable元数据。其他元数据将由其他系统（如UI）编写
，因此只能通过tap读取。这种类型的元数据称为non-discoverable元数据
参考的字段信息：
| Keyword | Tap Type | Discoverable? | Description |
|---|---|---|---|
selected |
any | non-discoverable | Either true or false. Indicates that this node in the schema has been selected by the user for replication. |
replication-method |
any | non-discoverable | Either FULL_TABLE, INCREMENTAL, or LOG_BASED. The replication method to use for a stream. |
replication-key |
any | non-discoverable | The name of a property in the source to use as a "bookmark". For example, this will often be an "updated-at" field or an auto-incrementing primary key (requires replication-method). |
view-key-properties |
database | non-discoverable | List of key properties for a database view. |
inclusion |
any | discoverable | Either available, automatic, or unsupported. available means the field is available for selection, and the tap will only emit values for that field if it is marked with "selected": true. automatic means that the tap will emit values for the field. unsupported means that the field exists in the source data but the tap is unable to provide it. |
selected-by-default |
any | discoverable | Either true or false. Indicates if a node in the schema should be replicated if a user has not expressed any opinion on whether or not to replicate it. |
valid-replication-keys |
any | discoverable | List of the fields that could be used as replication keys. |
schema-name |
any | discoverable | The name of the stream. |
forced-replication-method |
any | discoverable | Used to force the replication method to either FULL_TABLE or INCREMENTAL. |
table-key-properties |
database | discoverable | List of key properties for a database table. |
is-view |
database | discoverable | Either true or false. Indicates whether a stream corresponds to a database view. |
row-count |
database | discoverable | Number of rows in a database table/view. |
database-name |
database | discoverable | Name of database. |
sql-datatype |
database | discoverable | Represents the datatype of a database column. |
参考的数据格式
{
"metadata" : {
"selected" : true,
"some-other-metadata" : "whatever"
},
"breadcrumb" : ["properties", "some-field-name"]
}
上面的breadcrumb对象定义了到元数据所属节点的模式的路径。流的元数据将具有空的面包屑。
参考完整例子
{
"streams": [
{
"tap_stream_id": "users",
"stream": "users",
"schema": {
"type": ["null", "object"],
"additionalProperties": false,
"properties": {
"id": {
"type": [
"null",
"string"
],
},
"name": {
"type": [
"null",
"string"
],
},
"date_modified": {
"type": [
"null",
"string"
],
"format": "date-time",
}
}
},
"metadata": [
{
"metadata": {
"inclusion": "available",
"table-key-properties": ["id"],
"selected-by-default": true,
"valid-replication-keys": ["date_modified"],
"schema-name": "users",
},
"breadcrumb": []
},
{
"metadata": {
"inclusion": "automatic",
},
"breadcrumb": ["properties", "id"]
},
{
"metadata": {
"inclusion": "available",
"selected-by-default": true,
},
"breadcrumb": ["properties", "name"]
},
{
"metadata": {
"inclusion": "automatic",
},
"breadcrumb": ["properties", "date_modified"]
}
]
}
]
}
参考资料
https://github.com/singer-io/getting-started/blob/master/docs/DISCOVERY_MODE.md
