BigQuery 架构的定义/文档？

Posted 2023-03-24

【中文标题】BigQuery 架构的定义/文档？

【英文标题】：Definition/documentation for BigQuery schemas?

【发布时间】：2017-06-21 10:12:37

【问题描述】：

有谁知道 BigQuery 架构定义的文档在哪里？换句话说，您在上传文件时提供的 JSON 模式 - personsDataSchema.json in this example。

我已经在谷歌上搜索了很长时间，但我找不到任何关于模式的模式的文档。

我能得到的最接近的是documentation about auto-detecting schemas。但在不合适的情况下，您需要提供预定义的 JSON 模式，是否有任何文档说明哪些字段是必需的，哪些值是允许的？

【问题讨论】：

新行分隔的 JSON 是基础，然后是所有正常的字段/类型。见***.com/questions/41902054/…

感谢您的反馈。你介意为它创建一个功能请求吗？ issuetracker.google.com/issues/…。同时，您可以参考 API 的文档。例如，此链接定义表的架构：cloud.google.com/bigquery/docs/reference/rest/v2/tables#schema。不是对 JSON 的直接定义，但您可以弄清楚。

@HuaZhang 谢谢，我已经创建了一个问题。

【参考方案1】：

要定义一个模式，您基本上只需要定义 3 个字段：name、type 和 mode。

表中的每个字段都必须定义这 3 个键。例如，如果您有如下表格：

user_id    source
1          search
2          email

那么架构可以定义为：

["name": "user_id", "type": "INT64", "mode": "REQUIRED",
 "name": "source", "type": "STRING", "mode": "NULLABLE"]

键name只是描述了字段名，比如“user_id”。

type键为数据类型，如STRING、INTEGER、FLOAT等。目前，BigQuery 支持these types：

字符串 INT64 FLOAT64 布尔 BYTES（结束字节为您提供字符串表示形式）。 日期 日期时间 时间 时间戳 记录

现在，如果您打开文档，您会看到我们还有数据类型 ARRAY，它是一个 REPEATED 字段。稍后我将详细讨论它们。

第三个键 mode 可以是以下之一：

NULLABLE（允许值为NULL） 必需（不允许值为NULL） REPEATED（这是 ARRAY 字段，这意味着该字段基本上是一个值列表）。

那么，让我们以我们之前的例子，添加一个重复的字段（即ARRAY字段）来说明：

user_id    source    wishlist
1          search    ["sku 0", "sku 1"]
2          email     []
3          direct    ["sku 0", "sku 3"]

架构可以定义如下：

["name": "user_id", "type": "INT64", "mode": "REQUIRED",
 "name": "source", "type": "STRING", "mode": "NULLABLE",
 "name": "wishlist", "type": "STRING", "mode": "REPEATED"]

你有它，ARRAY 字段定义为字符串值的重复。

我们还剩下一种类型的字段，那就是 RECORD 字段 (STRUCT)。这些基本相同，只是我们还为它们定义了第四个键fields。由于 RECORD 包含其他字段，因此您还必须描述它们的定义；举个例子更容易理解：

user_id    source    wishlist            location.country    location.city
1          search    ["sku 0", "sku 1"]  USA                 NY
2          email     []                  USA                 LA
3          direct    ["sku 0", "sku 3"]  BR                  SP

这里，location 是一个 RECORD (STRUCT)，里面有 2 个键：country 和 city。这就是您为它们定义架构的方式：

["name": "user_id", "type": "INT64", "mode": "REQUIRED",
 "name": "source", "type": "STRING", "mode": "NULLABLE",
 "name": "wishlist", "type": "STRING", "mode": "REPEATED",
 "name": "location", "type": "RECORD", "mode": "NULLABLE", "fields": ["name": "country", "type": "STRING", "mode": "NULLABLE", "name": "city", "type": "STRING", "mode": "NULLABLE"]]

您想拥有 REPEATED 的 RECORDS 字段吗？当然，为什么不呢！例如，如果您希望客户在您的网站中拥有的每个 hit 都有一个 REPEATED 字段，您可以像这样定义架构：

["name": "user_id", "type": "INT64", "mode": "REQUIRED",
 "name": "source", "type": "STRING", "mode": "NULLABLE",
 "name": "wishlist", "type": "STRING", "mode": "REPEATED",
 "name": "location", "type": "RECORD", "mode": "NULLABLE", "fields": ["name": "country", "type": "STRING", "mode": "NULLABLE", "name": "city", "type": "STRING", "mode": "NULLABLE"],
 "name": "hit", "type": "RECORD", "mode": "REPEATED", "fields": ["name": "hitNumber", "type": "INT64", "mode": "NULLABLE", "name": "hitPage", "type": "STRING", "mode": "NULLABLE"]]

鉴于此，我们终于可以回答您的问题，dataPersons.json 架构将如何定义？

这是一行personsData的例子：

"kind": "person",
 "fullName": "John Doe",
 "age": 22,
 "gender": "Male",
 "phoneNumber": "areaCode": "206", "number": "1234567",
 "children": ["name": "Jane", "gender": "Female", "age": "6",
              "name": "John", "gender": "Male", "age": "15"],
 "citiesLived": ["place": "Seattle", "yearsLived": ["1995"],
                 "place": "Stockholm", "yearsLived": ["2005"]]

首先，我们有"kind": "person"。这很简单，它的架构是：

"name": "kind", "type": "STRING", "mode": "REQUIRED" or "NULLABLE"

phoneNumber 是一个包含两个内部字段 areaCode 和 number 的 RECORD (STRUCT) 字段。好吧，我们已经看到了如何定义它们！

"name": "phoneNumber",
 "type": "RECORD",
 "mode": "NULLABLE OR REQUIRED",
 "fields": ["name": "areaCode", "type": "INT64", "mode": "NULLABLE",
            "name": "number", "type": "INT64", "mode": "NULLABLE"]

现在children 和citiesLived 具有相同的定义，即它们都是RECORDs (STRUCT) 的REPEATED (ARRAY) 字段。就像我们上一个例子一样，这个例子也应该很简单； citiesLived 将被定义为：

"name": "citiesLived",
 "type": "RECORD",
 "mode": "REPEATED",
 "fields": ["name": "place", "type": "STRING", "mode": "NULLABLE",
            "name": "yearLived", "type": "INT64", "mode": "REPEATED"]

你有它。这基本上就是模式定义的全部内容。例如，如果您使用 Python，则想法是相同的。您导入类 SchemaField 来定义每个字段，如下所示：

from google.cloud.bigquery import SchemaField
field_kind = SchemaField(name="kind", type="STRING", mode="NULLABLE")

其他客户也会遵循同样的想法。

总而言之，您始终必须为表中的每个字段定义 3 个键：name、type 和 mode。如果该字段是 RECORD 类型，那么您还必须定义 fields 并且对于每个内部字段，您再次定义 3 个键（如果内部字段再次属于 RECORD 类型，则为 4 个）。

希望这可以更清楚地说明如何定义架构。如果您对此主题仍有任何疑问，请告诉我，我会更新答案。

【讨论】：

很好的答案！需要补充一点的是，默认模式是 NULLABLE，所以当你觉得懒惰时，可以跳过 NULLABLE 字段的模式。

在 python 中定义 RECORD 类型时，字段列表必须是 iterable - 注意此示例中嵌套字段后的 尾随逗号 ：bigquery.SchemaField('hyperparameters', 'RECORD', fields=( bigquery.SchemaField('payload', 'STRING'), ) )