Facets（分面）¶

Datasette 的 Facets 可用于为任何数据库表添加分面浏览界面。通过 Facets，表会与显示指定列中最常见值的摘要一起显示。可以选择这些值来进一步过滤表。

Screenshot showing facets against a table of congressional legislators. Suggested facets include state_rank and start and end dates, and the displayed facets are state, party and type. Each facet lists values along with a count of rows for each value.

Facets 可以通过两种方式指定：使用查询字符串参数，或者在表的 metadata.json 配置中。

查询字符串中的 Facets¶

要在 Datasette 表视图上为特定列开启分面，请在 URL 中添加一个或多个 _facet=COLUMN 参数。例如，如果您想为 city_id 和 state 列开启 Facets，请构建一个如下所示的 URL：

/dbname/tablename?_facet=state&_facet=city_id

这适用于 HTML 界面和 .json 视图。启用后，Facets 将导致 facet_results 块添加到 JSON 输出中，看起来像这样：

{
  "state": {
    "name": "state",
    "results": [
      {
        "value": "CA",
        "label": "CA",
        "count": 10,
        "toggle_url": "http://...?_facet=city_id&_facet=state&state=CA",
        "selected": false
      },
      {
        "value": "MI",
        "label": "MI",
        "count": 4,
        "toggle_url": "http://...?_facet=city_id&_facet=state&state=MI",
        "selected": false
      },
      {
        "value": "MC",
        "label": "MC",
        "count": 1,
        "toggle_url": "http://...?_facet=city_id&_facet=state&state=MC",
        "selected": false
      }
    ],
    "truncated": false
  }
  "city_id": {
    "name": "city_id",
    "results": [
      {
        "value": 1,
        "label": "San Francisco",
        "count": 6,
        "toggle_url": "http://...?_facet=city_id&_facet=state&city_id=1",
        "selected": false
      },
      {
        "value": 2,
        "label": "Los Angeles",
        "count": 4,
        "toggle_url": "http://...?_facet=city_id&_facet=state&city_id=2",
        "selected": false
      },
      {
        "value": 3,
        "label": "Detroit",
        "count": 4,
        "toggle_url": "http://...?_facet=city_id&_facet=state&city_id=3",
        "selected": false
      },
      {
        "value": 4,
        "label": "Memnonia",
        "count": 1,
        "toggle_url": "http://...?_facet=city_id&_facet=state&city_id=4",
        "selected": false
      }
    ],
    "truncated": false
  }
}

如果 Datasette 检测到某个列是外键，"label" 属性将自动从引用表中检测到的标签列派生。

默认返回的 Facet 结果数量是 30，由 default_facet_size 设置控制。您可以通过向查询字符串添加 ?_facet_size=100 在单个页面上增加此数量，最大不超过 max_returned_rows（默认为 1000）。

metadata.json 中的 Facets¶

您可以通过将 Facets 添加到 Datasette Metadata 文件中的 "facets" 键下，为特定表默认开启 Facets。

下面是一个示例，它为 sf-trees 数据库中 Street_Tree_List 表的 qLegalStatus 列默认开启分面：

{
  "databases": {
    "sf-trees": {
      "tables": {
        "Street_Tree_List": {
          "facets": ["qLegalStatus"]
        }
      }
    }
  }
}

以这种方式定义的 Facets 将始终显示在界面中并在 API 中返回，无论传递给视图的 _facet 参数如何。

您可以在元数据中使用 JSON 对象指定数组或日期 Facets，JSON 对象只有一个键 array 或 date，值指定列名，像这样：

{
  "facets": [
    {"array": "tags"},
    {"date": "created"}
  ]
}

您可以使用 facet_size 更改表的默认 Facet 大小（每个 Facet 显示的结果数量）：

{
  "databases": {
    "sf-trees": {
      "tables": {
        "Street_Tree_List": {
          "facets": ["qLegalStatus"],
          "facet_size": 10
        }
      }
    }
  }
}

建议的 Facets¶

Datasette 的表 UI 将根据以下标准建议用户应用的 Facets：

对于当前已过滤的数据，是否存在某些列，如果应用为 Facet...

将返回 30 个或更少的唯一选项
将返回多于一个唯一选项
返回的唯一选项少于已过滤的总行数
并且用于评估此标准的查询可在 50ms 内完成

最后一点尤为重要：Datasette 会为页面上显示的每个列运行一个查询，这可能会非常耗时——因此为了避免加载缓慢，它为每个查询设置了仅 50ms 的时间限制。这意味着对于包含数百万条记录的表，建议的 Facets 不太可能出现。

使用索引加速 Facets¶

通过在您希望进行分面的列上添加索引，可以大大提高 Facets 的性能。可以使用 sqlite3 命令行工具添加索引。以下是如何在名为 Food_Trucks 的表中为 state 列添加索引：

$ sqlite3 mydatabase.db
SQLite version 3.19.3 2017-06-27 16:48:08
Enter ".help" for usage hints.
sqlite> CREATE INDEX Food_Trucks_state ON Food_Trucks("state");

或者使用 sqlite-utils 命令行工具：

$ sqlite-utils create-index mydatabase.db Food_Trucks state

按 JSON 数组进行 Facet¶

如果您的 SQLite 安装提供了 json1 扩展（您可以使用 /-/versions 检查），Datasette 将自动检测包含 JSON 数组值的列，并为这些列提供分面界面。

这对于建模标签等内容非常有用，无需将其分解到新表中。

示例在这里：latest.datasette.io/fixtures/facetable?_facet_array=tags

按日期进行 Facet¶

如果 Datasette 在前 100 个值中发现任何包含日期的列，它将为这些值的日期提供分面界面。这对于时间戳值尤其有效，例如 2019-03-01 12:44:00。

示例在这里：latest.datasette.io/fixtures/facetable?_facet_date=created