此页面由 Cloud Translation API 翻译。

示例 SQL 查询

本文档包含对存储在升级为使用 Log Analytics 的日志存储分区。在这些存储分区中，您可以从以下位置运行 SQL 查询： Google Cloud 控制台中的日志分析页面。如需更多示例，请参阅 logging-analytics-samples 和 security-analytics GitHub 代码库。

本文档不介绍 SQL 以及如何路由和存储日志条目。对于相关信息，请参阅后续步骤部分。

准备工作

如需使用本文档的 Log Analytics 页面中显示的查询，请执行以下操作：将 TABLE 替换为对应的表名称添加到您要查询的视图表名称的格式为 project_ID.region.bucket_ID.view_ID。您可以找到在 Log Analytics 页面上查看；日志的默认查询视图在 FROM 语句中列出表名称。对于有关如何访问默认查询的信息请参阅查询日志视图。
要在 BigQuery Studio 页面中，将将 TABLE 替换为表路径关联的数据集中。例如，查询关联数据集 mydataset 上的视图 _AllLogs 位于项目“myproject”中，请将此字段设为 myproject.mydataset._AllLogs：

在 Google Cloud 控制台中，前往 BigQuery 页面：
前往 BigQuery Studio

您也可以使用搜索栏查找此页面。
如需打开 Log Analytics 页面，请执行以下操作：
1. 在 Google Cloud 控制台中，前往 Log Analytics 页面：
  转到 Log Analytics
  
  如果您使用搜索栏查找此页面，请选择子标题为 Logging 的结果。
2. 可选：如需确定日志视图的表架构，请执行以下操作：在日志视图列表中，找到该视图，然后选择视图名称。
此时会显示表的架构。您可以使用过滤条件字段来查找特定字段您无法修改架构。

过滤日志

SQL 查询确定要处理表中的哪些行，然后对它们进行分组行并执行聚合操作。未分组和汇总时操作的列表，查询结果包括由过滤器操作。本部分中的示例对过滤进行了说明。

按时间过滤

要设置查询的时间范围请使用时间范围选择器。在发生查询时，系统会自动使用此选择器未在 WHERE 子句中指定 timestamp 字段。例如，要查看过去一周的数据，请选择过去 7 天，从时间范围选择器。您还可以使用时间范围选择器来指定开始时间和结束时间、查看时段以及更改时区。

如果您在 WHERE 子句中包含 timestamp 字段，则时间范围。以下示例按使用 TIMESTAMP_SUB 函数，该函数可让您指定回溯期从当前时间开始的时间间隔：

WHERE
  timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)

有关如何按时间过滤的详情，请参阅时间函数和时间戳函数。

按资源过滤

如需按资源过滤，请添加 resource.type 限制。

例如，以下查询可读取最近一个小时的数据，然后保留资源类型与 gce_instance 匹配的行，然后进行排序最多可显示 100 个条目：

SELECT
  timestamp, log_name, severity, json_payload, resource, labels
FROM
  `TABLE`
WHERE
  resource.type = "gce_instance"
ORDER BY timestamp ASC
LIMIT 100

按严重程度过滤

您可以按特定严重程度过滤，并设置如下限制： severity = 'ERROR'。另一种方法是使用 IN 语句并指定一组有效值。

例如，以下查询可读取最近一小时的数据，以及然后仅保留包含 severity 字段且值是 'INFO' 或 'ERROR'：

SELECT
  timestamp, log_name, severity, json_payload, resource, labels
FROM
  `TABLE`
WHERE
  severity IS NOT NULL AND
  severity IN ('INFO', 'ERROR')
ORDER BY timestamp ASC
LIMIT 100

上一个查询按 severity 字段的值进行过滤。不过，您还可以编写按日志严重性的数值进行过滤的查询。例如，如果您将 severity 行替换为以下代码：查询会返回严重级别至少为 NOTICE 的所有日志条目：

  severity_number IS NOT NULL AND
  severity_number > 200

有关枚举值的信息，请参阅 LogSeverity。

按日志名称过滤

要按日志名称进行过滤，您可以为 log_name 或 log_id 字段。log_name 字段包含路径。也就是说，此字段包含类似 projects/myproject/logs/mylog 的值。 log_id 字段仅存储日志名称，例如 mylog。

例如，以下查询可读取最近一个小时的数据，然后并保留 log_id 字段中的值是 cloudaudit.googleapis.com/data_access，然后对结果：

SELECT
  timestamp, log_id, severity, json_payload, resource, labels
FROM
  `TABLE`
WHERE
  log_id = "cloudaudit.googleapis.com/data_access"
ORDER BY timestamp ASC
LIMIT 100

按资源标签过滤

大多数受监控的资源描述符都会定义标签，用于标识特定资源。例如，Compute Engine 实例的描述符包含可用区、项目 ID 和实例 ID 的标签。当写入日志条目，系统会为每个字段分配值。以下是例如：

{
   type: "gce_instance"
   labels: {
      instance_id: "1234512345123451"
      project_id: "my-project"
      zone: "us-central1-f"
   }
}

由于 labels 字段的数据类型是 JSON，因此包括限制像 resource.labels.zone = "us-centra1-f" 这样的查询会导致语法错误。要获取数据类型为 JSON 的字段的值，请使用函数 JSON_VALUE。

例如，以下查询可读取最新的数据，然后保留资源是一个 Compute Engine 实例位于 us-central1-f 可用区中：

SELECT
  timestamp, log_name, severity, JSON_VALUE(resource.labels.zone) AS zone, json_payload, resource, labels
FROM
  `TABLE`
WHERE
  resource.type = "gce_instance" AND
  JSON_VALUE(resource.labels.zone) = "us-central1-f"
ORDER BY timestamp ASC
LIMIT 100

了解可以检索和转换 JSON 的所有函数请参阅 JSON 函数。

按 HTTP 请求过滤

过滤表，使其仅包含与 HTTP 请求对应的行或者回复，添加 http_request IS NOT NULL 限制：

SELECT
  timestamp, log_name, severity, http_request, resource, labels
FROM
  `TABLE`
WHERE
  http_request IS NOT NULL
ORDER BY timestamp
LIMIT 100

以下查询仅包含与 GET 或 POST 对应的行请求：

SELECT
  timestamp, log_name, severity, http_request, resource, labels
FROM
  `TABLE`
WHERE
  http_request IS NOT NULL AND
  http_request.request_method IN ('GET', 'POST')
ORDER BY timestamp ASC
LIMIT 100

按 HTTP 状态过滤

要按 HTTP 状态过滤，请修改 WHERE 子句以要求使用定义 http_request.status 字段：

SELECT
  timestamp, log_name, http_request.status, http_request, resource, labels
FROM
  `TABLE`
WHERE
  http_request IS NOT NULL AND
  http_request.status IS NOT NULL
ORDER BY timestamp ASC
LIMIT 100

如需确定字段中存储的数据类型，请查看架构或显示字段。上一个查询的结果显示， http_request.status 字段存储整数值。

按 JSON 类型的字段过滤

如需从数据类型为 JSON 的列中提取值，请使用函数 JSON_VALUE。

请考虑以下查询：

SELECT
  json_payload
FROM
  `TABLE`
WHERE
  json_payload.status IS NOT NULL

和

SELECT
  json_payload
FROM
  `TABLE`
WHERE
  JSON_VALUE(json_payload.status) IS NOT NULL

前面的查询测试 json_payload 列的值；内容取决于日志条目的内容。两个查询舍弃不包含“json_payload”列的行。这两个查询之间的差异就是最后一行，它定义了针对 NULL 进行测试的内容。现在，假设有一个包含两行的表。在一个行中，json_payload 列的格式如下：

{
    status: {
        measureTime: "1661517845"
    }
}

在另一行中，json_payload 列具有不同的结构：

{
    @type: "type.googleapis.com/google.cloud.scheduler.logging.AttemptFinished"
    jobName: "projects/my-project/locations/us-central1/jobs/test1"
    relativeUrl: "/food=cake"
    status: "NOT_FOUND"
    targetType: "APP_ENGINE_HTTP"
}

前面两行都满足限制 json_payload.status IS NOT NULL。也就是说，查询结果包含这两行。不过，当限制为 JSON_VALUE(json_payload.status) IS NOT NULL 时，结果中仅包含第二行

按正则表达式过滤

要返回与正则表达式匹配的子字符串，请使用函数 REGEXP_EXTRACT。此函数的返回值类型为 STRING 或 BYTES。

以下查询会显示最近收到的日志条目，并保留带有 json_payload.jobName 字段的条目，然后显示部分以 test 开头：

SELECT
  timestamp, REGEXP_EXTRACT(JSON_VALUE(json_payload.jobName), r".*(test.*)$") AS name,
FROM
  `TABLE`
WHERE
  json_payload.jobName IS NOT NULL
ORDER BY timestamp DESC
LIMIT 20

如需查看更多示例，请参阅 REGEXP_EXTRACT 文档。有关其他正则表达式请参阅函数、运算符和条件。

此示例中显示的查询效率低下。对于子字符串匹配，例如如图中所示，请使用 CONTAINS_SUBSTR 函数。

对日志条目进行分组和汇总

本部分在前面的示例的基础上，说明了如何对表格中的行进行分组和汇总。如果您未指定分组，但则输出单个结果，因为 SQL 会将所有将满足 WHERE 子句的所有行作为一个组。

每个 SELECT 表达式都必须包含在组字段中或者进行汇总。

按时间分组

如需按时间对数据进行分组，请使用函数 TIMESTAMP_TRUNC。该方法将时间戳截断到指定的粒度，例如 MINUTE。对于例如 15:30:11 的时间戳，其格式为 hours:minutes:seconds，当粒度设置为 15:30:00 时， MINUTE。

以下查询读取在由时间范围选择器，然后保留 json_payload.status 字段的值不是 NULL 的行。该查询按小时截断每行的时间戳，然后对行（按截断的时间戳和状态排序）：

SELECT
  TIMESTAMP_TRUNC(timestamp, HOUR) AS hour,
  JSON_VALUE(json_payload.status) AS status,
  COUNT(*) AS count
FROM
  `TABLE`
WHERE
  json_payload IS NOT NULL AND
  JSON_VALUE(json_payload.status) IS NOT NULL
GROUP BY hour,status
ORDER BY hour ASC

如需查看更多示例，请参阅 TIMESTAMP_TRUNC 文档。如需了解其他基于时间的函数，请参阅日期时间函数。

按资源分组

以下查询会读取最近一个小时的数据，然后将按资源类型细分的行数。然后计算每种类型的行数，并返回一个包含两列的表。第一列列出了相应资源第二列是该资源类型的行数：

SELECT
   resource.type, COUNT(*) AS count
FROM
  `TABLE`
GROUP BY resource.type
LIMIT 100

按严重程度分组

以下查询可读取最近一个小时的数据，然后保留行包含 severity 字段的应用。然后，查询会按严重级别对行进行分组，计算每个组的行数：

SELECT
  severity, COUNT(*) AS count
FROM
  `TABLE`
WHERE
  severity IS NOT NULL
GROUP BY severity
ORDER BY severity
LIMIT 100

按`log_id`分组

以下查询的结果是一个包含两列的表。第一个列列出了日志名称，第二列列出了写入日志的日志条目。通过查询会按条目数对结果进行排序：

SELECT
  log_id, COUNT(*) AS count
FROM
  `TABLE`
GROUP BY log_id
ORDER BY count DESC
LIMIT 100

计算 HTTP 请求的平均延迟时间

以下查询展示了按多列分组，并计算平均值。查询按 HTTP 请求中包含的网址对行进行分组，以及 labels.checker_location 字段的值。更新后对行进行分组，则查询会计算每个组的平均延迟时间：

SELECT
  JSON_VALUE(labels.checker_location) AS location,
  AVG(http_request.latency.seconds) AS secs, http_request.request_url
FROM
  `TABLE`
WHERE
  http_request IS NOT NULL AND
  http_request.request_method IN ('GET')
GROUP BY http_request.request_url, location
ORDER BY location
LIMIT 100

在前面的表达式中，需要 JSON_VALUE 才能提取值因为 labels.checker_location 字段的数据类型 labels 是 JSON。不过，您不应使用此函数从 http_request.latency.seconds 字段。第二个字段的数据类型为整数。

计算为子网测试发送的平均字节数

以下查询说明了如何显示按位置发送的字节数。

查询读取最近一小时的数据，然后仅保留这些行其资源类型列为 gce_subnetwork，其 json_payload 列的值不是 NULL。接下来，查询资源。与之前的示例不同，在前面的示例中，数据以数字形式值，bytes_sent 字段的值是一个字符串，因此您必须在计算平均值之前，将该值转换为 FLOAT64：

SELECT JSON_VALUE(resource.labels.location) AS location,
   AVG(CAST(JSON_VALUE(json_payload.bytes_sent) AS FLOAT64)) AS bytes
FROM
  `TABLE`
WHERE
  resource.type = "gce_subnetwork" AND
  json_payload IS NOT NULL
GROUP BY location
LIMIT 100

上一个查询的结果是一个表，表中的每一行都列出了一个位置以及为该位置发送的平均字节数。

了解可以检索和转换 JSON 的所有函数请参阅 JSON 函数。

如需了解 CAST 和其他转换函数，请参阅转换函数。

统计包含与模式匹配的字段的日志条目数

要返回与正则表达式匹配的子字符串，请使用函数 REGEXP_EXTRACT。此函数的返回值类型为 STRING 或 BYTES。

以下查询将保留值为 json_payload.jobName 字段中的值不是 NULL。然后，它会按名称后缀（以尽在 test。最后，查询计算每组中的条目数：

SELECT
  REGEXP_EXTRACT(JSON_VALUE(json_payload.jobName), r".*(test.*)$") AS name,
  COUNT(*) AS count
FROM
  `TABLE`
WHERE
  json_payload.jobName IS NOT NULL
GROUP BY name
ORDER BY count
LIMIT 20

如需查看更多示例，请参阅 REGEXP_EXTRACT 文档。有关其他正则表达式请参阅函数、运算符和条件。

跨列搜索

本部分介绍了可用于搜索多个列。

基于词元的搜索

要在表格中搜索与一组搜索字词匹配的条目，使用函数 SEARCH。此函数需要两个参数：搜索位置以及搜索查询。由于 SEARCH 函数对数据搜索方式有特定的规则，我们建议您阅读 SEARCH 文档。

以下查询仅保留具有字段的行与“35.193.12.15”完全匹配：

SELECT
  timestamp, log_id, proto_payload, severity, resource.type, resource, labels
FROM
  `TABLE` AS t
WHERE
  proto_payload IS NOT NULL AND
  log_id = "cloudaudit.googleapis.com/data_access" AND
  SEARCH(t,"`35.193.12.15`")
ORDER BY timestamp ASC
LIMIT 20

在上一个查询中，反引号用于封装要搜索的值。这个可确保 SEARCH 函数在字段值和反引号之间的值。

如果查询字符串中省略反引号，则查询字符串将被拆分（在 SEARCH 文档中定义的规则）。例如，当运行以下语句时，查询字符串拆分为四个词元：“35”“193”“12”和“15”：

  SEARCH(t,"35.193.12.15")

当单个字段时，前面的 SEARCH 语句匹配一行匹配全部四个词元。令牌的顺序无关紧要。

您可以在一个查询中包含多个 SEARCH 语句。例如，在那么您可以将日志 ID 中的过滤条件替换为语句：

  SEARCH(t,"`cloudaudit.googleapis.com/data_access`")

前一个语句搜索整个表，而原始语句仅搜索 log_id 列。

要对某一列执行多次搜索，请使用空间。例如，以下语句与包含字段包含“Hello World”“happy”和“days”：

  SEARCH(t,"`Hello World` happy days")

最后，您可以搜索表格中的特定列，而不是搜索整个表。例如，以下语句仅搜索名为 text_payload 和 json_payload 的列：

   SEARCH((text_payload, json_payload) ,"`35.222.132.245`")

如需了解如何处理 SEARCH 函数的参数，请参阅 BigQuery 参考页面搜索功能。

子字符串搜索

要执行不区分大小写的测试来确定表达式，请使用函数 CONTAINS_SUBSTR。当该值存在时，此函数会返回 TRUE，并且否则为 FALSE。搜索值必须是 STRING 字面量，但不能是字面量 NULL。

例如，以下查询会提取所有数据访问审核日志条目特定 IP 地址，且时间戳在特定时间范围内。最后，查询会对结果进行排序，然后显示时间最早的 20 条结果：

SELECT
  timestamp, log_id, proto_payload, severity, resource.type, resource, labels
FROM
  `TABLE` AS t
WHERE
  proto_payload IS NOT NULL AND
  log_id = "cloudaudit.googleapis.com/data_access" AND
  CONTAINS_SUBSTR(t,"35.193.12.15")
ORDER BY timestamp ASC
LIMIT 20

上一个查询会执行子字符串测试。因此，包含 “35.193.12.152”与 CONTAINS_SUBSTR 语句匹配。

合并多个来源的数据

查询语句会扫描一个或多个表或表达式，并返回计算结果行。例如，您可以使用查询语句将同一数据集中不同表或数据集上的 SELECT 语句的结果然后从合并的数据中选择列。

使用联接合并两个表中的数据

要合并两个表中的信息，请使用联接运算符。连接的类型和使用的条件子句决定了合并和舍弃行的方式。

以下查询为您提供了json_payload 由同一跟踪记录 span 写入的两个不同的表。查询会执行内 JOIN，其值是两个表中的 span_id 和 trace 列匹配。在这条结果中然后，查询会选择 timestamp、severity 和 json_payload 字段来自TABLE_1的json_payload字段 TABLE_2，以及 span_id 的值以及用于联接两个表的 trace 字段，最多返回 100 个行：

SELECT
  a.timestamp, a.severity, a.json_payload, b.json_payload, a.span_id, a.trace
FROM `TABLE_1` a
JOIN `TABLE_2` b
ON
  a.span_id = b.span_id AND
  a.trace = b.trace
LIMIT 100

使用并集结合多项选择

合并两个或更多 SELECT 语句的结果并舍弃重复行，请使用 UNION 运算符。保留重复项则使用 UNION ALL 运算符。

以下查询从 TABLE_1 - 将结果与最近一个小时的内容合并来自 TABLE_2 的数据，按升序对合并的数据进行排序 timestamp，然后显示最早的 100 个条目：

SELECT
  timestamp, log_name, severity, json_payload, resource, labels
FROM(
  SELECT * FROM `TABLE_1`
  UNION ALL
  SELECT * FROM `TABLE_2`
)
ORDER BY timestamp ASC
LIMIT 100

后续步骤

如需了解如何路由和存储日志条目，请参阅以下文档：

如需查看 SQL 参考文档，请参阅以下文档：