PQL 구문 및 사용법
PQL은 SQL과 유사한 객체 쿼리를 위한 언어입니다. PQL 구문은 SQL 구문과 비슷하지만 몇 가지 차이점이 여기에 설명되어 있습니다. 이 섹션에서는 PQL 구문 및 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>
Notes
- PQL 키워드는 대소문자를 구분하지 않습니다.
- 문자열은 바인드 매개변수에 사용될 때 자동으로 이스케이프 처리됩니다. 그렇지 않은 경우 다음 단계를 따릅니다.
작은따옴표 안의 문자열 (아포스트로피)의 경우 추가 아포스트로피를 작은따옴표 쌍으로 작성하여 이스케이프 처리합니다.
예:"WHERE name = 'Company''s name'"
키워드 (대소문자를 구분하지 않음)
WHERE
- 0개 이상의 조건 집합을 표현하며 선택적으로 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
- 반환된 결과를 오름차순('A'가 첫 번째인ASC
) 또는 내림차순(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
속성 값 대신 변수 2개 입력):// 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='v202402') 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에서 보기