PQL 语法和用法
PQL 是一种类似于 SQL 的语言,用于查询对象。PQL 语法与 SQL 语法类似,但有几点不同(如下文所述)。本部分介绍 PQL 语法以及如何使用它来过滤各种对象类型。
PQL 语法总结如下:
[WHERE <condition> {[AND | OR] <condition> ...}] [ORDER BY <property> [ASC | DESC]] [LIMIT {[<offset>,] <count>} | {<count> OFFSET <offset>}] <condition> := <property> { = | != } <value> <condition> := <property> { = | != } <bind variable> <condition> := <property> IN <list> <condition> := NOT <property> IN <list> <condition> := <property> LIKE <wildcard%match> <condition> := <property> IS NULL <bind variable> := :<name>
备注
- PQL 关键字不区分大小写。
- 在绑定参数中使用时,字符串会自动转义。否则:
对于使用单引号(撇号)的字符串,将任何其他撇号编写为一对单引号来对其进行转义。
示例:"WHERE name = 'Company''s name'"
关键字(不区分大小写)
WHERE
- 表示一组零或多个条件,可选择使用 AND 或 OR 短语连接。您可以将 AND 或 OR 短语与括号捆绑在一起。执行查询""
(空字符串)可返回所有内容。示例:
WHERE width = 728
WHERE width = 728 AND height = 90
WHERE (width = 728 AND height = 90) OR id IN (5008, 8745, 3487)
OR
- 用于连接多个条件(只有一个条件必须为 true)。如果您要查看单个属性的任何一个值,请考虑使用IN
子句。示例:
WHERE width = 728 OR height = 90
AND
- 用于连接多个条件(使用 AND 子句时,所有这些条件都必须满足)。示例:
WHERE type = 'AGENCY' AND name IN ('CompanyNameA', 'CompanyNameB')
ORDER BY
- 按升序(ASC
,“A”排在首位)或降序(DESC
,“A”排在末位)对返回的结果进行排序。如果未指定方向,则默认为ASC
。如果未添加该子句,则首个字段默认为ASC
。示例:
WHERE id IN (5008, 8745, 3487) ORDER BY id
LIMIT
- 要返回的结果数量。LIMIT
还可以包含<offset>
,指定从开始算起与结果集偏差的行数。示例(两个示例返回的结果集相同):
WHERE type = 'AGENCY' LIMIT 50 OFFSET 50
WHERE type = 'AGENCY' LIMIT 50,50
OFFSET
- 与开始返回值的偏差。可用此来浏览结果。示例(返回结果 51-100):
WHERE type = 'AGENCY' LIMIT 50 OFFSET 50
。<property>
- 对象公开的属性之一。每个对象公开不同的属性,您可以使用 PQL 按这些属性进行过滤;您通常无法按对象支持的所有属性进行过滤,因此请查看下面的列表,了解哪些属性支持 PQL 查询。例如,您可以过滤的广告素材属性包括id
、name
、width
和height
。<value>
- 应使用单引号 (') 引用字符串值。数值可选择使用或不使用引号。不支持通配符。IN
- 将属性值与列表中的每一项进行比较;如果有任何值匹配,则为肯定匹配。IN
运算符等同于许多=
查询(每个值对应一个查询)一起进行 OR 运算。这些值以逗号分隔值列表的形式指定,并用括号括起来:(a, b, c)。列表中的所有值都会接受评估。示例:
WHERE name IN ('CompanyNameA', 'CompanyNameB')
NOT IN
- 将属性值与列表中的每一项进行比较;如果没有任何值匹配,则为肯定匹配。NOT IN
运算符等同于许多!=
查询(每个值对应一个查询)一起进行 OR 运算。这些值以逗号分隔值列表的形式指定,并用括号括起来:(a, b, c)。列表中的所有值都会接受评估。示例:
WHERE NOT name IN ('CompanyNameA', 'CompanyNameB')
LIKE
- 可让您使用通配符字符串匹配查询对象。百分号 (%
) 表示 0 个、1 个或多个字符。使用一对字符串将要匹配的搜索字符串括起来。示例:
WHERE name LIKE 'foo %searchString% bar'
WHERE name LIKE 'Aus%'
IS NULL
- 可让您查询具有未定义属性值的对象。一个典型示例是通过查询父 ID 为 null 的AdUnit
来查询根AdUnit
。示例:
WHERE parentId IS NULL
<bind variable>
- 您可以在 PQL 查询中使用Value
对象代替硬编码的 <value> 值。在 PQL 中,绑定变量使用不含空格、以冒号 (:) 开头的字符串名称命名。示例(创建一个查询,并输入两个变量来代替硬编码的
id
和status
属性值):// Create two mapped parameters: id and status String_ValueMapEntry[] values = new String_ValueMapEntry[2]; values[0] = new String_ValueMapEntry("id", new NumberValue(null, "123")); values[1] = new String_ValueMapEntry("status", new TextValue(null, "APPROVED")); // Create our statement and map our bind variables Statement statement = new Statement(); statement.setQuery("WHERE id = :id AND status = :status LIMIT 500"); statement.setValues(values);
DateTime
字段 - 您可以通过为绑定变量分配DateTime
值或使用 ISO 8601 格式的字符串,按日期和时间进行过滤。// Create a bind variable: startDateTime String_ValueMapEntry[] values = new String_ValueMapEntry[1]; values[0] = new String_ValueMapEntry("startDateTime", new DateTimeValue(null, dateTime)); // Create our statement and map our bind variables Statement statement = new Statement(); statement.setQuery("WHERE endDateTime < '2019-01-01T00:00:00' AND startDateTime > :startDateTime LIMIT 500"); statement.setValues(values);
使用 PQL 提取匹配表
匹配表为数据传输文件中包含的原始值提供了一种查询机制,从而让您能够将广告投放信息(例如广告单元或订单项)与存储在数据库中的预分配值进行匹配。
如果您是通过 ReportService 或数据传输报表生成报表,则可能需要使用额外的字段来补充报告数据。例如,对于包含 LINE_ITEM_ID 维度的报告或具有 LineItemId 字段的数据传输事件,您可以创建一个匹配表,其中包含每个订单项的开始日期、结束日期、类型、状态和其他实用属性。
有几种方法可以实现此匹配功能:
- 使用 BigQuery Data Transfer Service 提供的预制匹配表。请注意,这些匹配表并不包含所有实体字段。
- 有效的方法是使用任何可用的 PublisherQueryLanguageService 表格。
- 如果实体没有 BigQuery 或 PQL 表,或者表缺少您所需的字段,您可以直接查询该实体的服务,例如 OrderService。
Python
设置报告查询
首先创建一个报告作业,指定维度、列和日期范围等报告参数。
# Set the start and end dates of the report to run (past 8 days). end_date = date.today() start_date = end_date - timedelta(days=8) # Create report job. report_job = { 'reportQuery': { 'dimensions': ['LINE_ITEM_ID', 'LINE_ITEM_NAME'], 'columns': ['AD_SERVER_IMPRESSIONS', 'AD_SERVER_CLICKS', 'AD_SERVER_CTR', 'AD_SERVER_CPM_AND_CPC_REVENUE', 'AD_SERVER_WITHOUT_CPD_AVERAGE_ECPM'], 'dateRangeType': 'CUSTOM_DATE', 'startDate': start_date, 'endDate': end_date } }
下载报告
# Initialize a DataDownloader. report_downloader = client.GetDataDownloader(version='v202405') try: # Run the report and wait for it to finish. report_job_id = report_downloader.WaitForReport(report_job) except errors.AdManagerReportError as e: print('Failed to generate report. Error was: %s' % e) with tempfile.NamedTemporaryFile( suffix='.csv.gz', mode='wb', delete=False) as report_file: # Download report data. report_downloader.DownloadReportToFile( report_job_id, 'CSV_DUMP', report_file)
下载 Line_Item PQL 表格中的数据
如需使报表与其他订单项数据保持一致,您可以使用 Line_Item PQL 表格。
# Create a PQL query to fetch the line item data line_items_pql_query = ('SELECT Id, LineItemType, Status FROM LineItem') # Download the response from PQL select statement line_items = report_downloader.DownloadPqlResultToList(line_items_pql_query)
将报告数据与订单项数据相联接
此示例使用 Pandas 库,因为它可以大幅简化表格数据的处理。在这里,它用于将报告数据与 PQL 数据相联接,以生成匹配表。
# Use pandas to join the two csv files into a match table report = pandas.read_csv(report_file.name) line_items = pandas.DataFrame(data=line_items[1:], columns=line_items[0]) merged_result = pandas.merge(report, line_items, left_on='Dimension.LINE_ITEM_ID', right_on='id') merged_result.to_csv('~/complete_line_items_report.csv', index=False)在 GitHub 上查看