Panduan Developer Bahasa Kueri Penayang (PQL)

Sintaksis dan penggunaan PQL

PQL adalah bahasa yang mirip SQL untuk membuat kueri objek. Sintaksis PQL mirip dengan SQL, dengan beberapa perbedaan yang dijelaskan di sini. Bagian ini menjelaskan sintaksis PQL, dan cara menggunakannya untuk memfilter berbagai jenis objek.

Sintaksis PQL dapat dirangkum sebagai berikut:

[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>

Catatan

  • Kata kunci PQL tidak peka huruf besar/kecil.
  • String akan otomatis di-escape saat digunakan dalam parameter binding. Atau:

    • Untuk string dalam tanda petik tunggal (apostrof), hindari apostrof tambahan dengan menulisnya sebagai sepasang tanda petik tunggal.

      Contoh: "WHERE name = 'Company''s name'"

Kata kunci (tidak peka huruf besar/kecil)

  • WHERE - Mengekspresikan kumpulan nol atau beberapa kondisi, yang digabungkan secara opsional menggunakan frasa AND atau OR. Anda dapat menggabungkan frasa DAN atau ATAU dengan tanda kurung. Mengeksekusi kueri "" (kosong string) menampilkan semuanya.

    Contoh: WHERE width = 728
    WHERE width = 728 AND height = 90
    WHERE (width = 728 AND height = 90) OR id IN (5008, 8745, 3487)

  • OR - Menggabungkan beberapa kondisi, yang hanya satu yang harus bernilai benar. Jika Anda ingin memeriksa salah satu dari beberapa nilai untuk satu Anda, pertimbangkan untuk menggunakan klausa IN.

    Contoh: WHERE width = 728 OR height = 90

  • AND - Menggabungkan beberapa kondisi yang semuanya harus puas dengan penggunaan klausa AND.

    Contoh: WHERE type = 'AGENCY' AND name IN ('CompanyNameA', 'CompanyNameB')

  • ORDER BY - Mengurutkan hasil yang ditampilkan dalam menaik (ASC dengan 'A' berada di urutan pertama) atau menurun (DESC dengan 'A' adalah yang terakhir). Jika arah tidak ditentukan, nilai defaultnya adalah ASC. Jika klausa ini tidak disertakan defaultnya adalah ASC di kolom pertama.

    Contoh: WHERE id IN (5008, 8745, 3487) ORDER BY id

  • LIMIT - Jumlah hasil yang akan ditampilkan. Tujuan LIMIT juga dapat menyertakan <offset>, yang berapa banyak baris dari awal untuk mengimbangi set hasil Anda.

    Contoh (kedua contoh menampilkan kumpulan hasil yang sama):
    WHERE type = 'AGENCY' LIMIT 50 OFFSET 50
    WHERE type = 'AGENCY' LIMIT 50,50

  • OFFSET - Offset ke set hasil untuk mulai menampilkan nilai. Gunakan ini untuk menelusuri hasil.

    Contoh (menampilkan hasil 51-100):
    WHERE type = 'AGENCY' LIMIT 50 OFFSET 50.

  • <property> - Salah satu properti yang diekspos oleh objek. Setiap objek mengekspos properti berbeda yang dapat Anda filter, menggunakan PQL; Anda biasanya tidak dapat memfilter semua properti yang didukung oleh jadi periksa daftar di bawah ini untuk melihat properti mana yang mendukung kueri PQL. Misalnya, properti materi iklan yang dapat Anda filter dengan menyertakan id, name, width, dan height.
  • <value> - Nilai string harus dikutip dengan tanda kutip tunggal ('). Nilai angka dapat diberi tanda kutip atau tidak. Karakter pengganti tidak didukung.
  • IN - Membandingkan nilai properti dengan setiap item dalam daftar; jika ada yang cocok, itu adalah kecocokan positif. Operator IN setara dengan banyak kueri =, satu untuk setiap nilai, yang digabungkan dengan OR. Nilai ditetapkan sebagai daftar yang dipisahkan oleh koma dari nilai yang diapit tanda kurung: (a, b, c). Semua nilai dalam daftar dievaluasi.

    Contoh: WHERE name IN ('CompanyNameA', 'CompanyNameB')

  • NOT IN - Membandingkan nilai properti dengan setiap item dalam daftar; jika tidak ada yang cocok, itu adalah pencocokan positif. Operator NOT IN setara dengan banyak kueri !=, satu untuk setiap nilai, yang digabungkan dengan OR. Nilai ditetapkan sebagai daftar yang dipisahkan oleh koma dari nilai yang diapit tanda kurung: (a, b, c). Semua nilai dalam daftar dievaluasi.

    Contoh: WHERE NOT name IN ('CompanyNameA', 'CompanyNameB')

  • LIKE - Memungkinkan Anda membuat kueri objek menggunakan pencocokan string karakter pengganti. Tanda persen (%) mewakili nol, satu, atau beberapa karakter. Gunakan pasangan untuk mengapit string penelusuran yang dicocokkan.

    Contoh: WHERE name LIKE 'foo %searchString% bar'
    WHERE name LIKE 'Aus%'

  • IS NULL - Memungkinkan Anda membuat kueri objek dengan nilai properti yang tidak ditentukan. Contoh klasiknya adalah membuat kueri untuk root AdUnit dengan membuat kueri AdUnit yang memiliki null ID induk.

    Contoh: WHERE parentId IS NULL.

  • <bind variable> - Anda dapat menggunakan Value objek sebagai pengganti <value> hard code dalam kueri PQL. Variabel binding dirujuk dalam PQL menggunakan nama string tanpa spasi, yang dimulai dengan : (titik dua).

    Contoh (Membuat kueri dan memasukkan dua variabel sebagai pengganti nilai properti id dan status yang di-hardcode):

    // 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 kolom - Anda dapat memfilter menurut tanggal dan waktu berdasarkan menetapkan nilai DateTime ke variabel binding, atau dengan menggunakan string yang diformat sesuai dengan 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);

Mengambil tabel pencocokan dengan PQL

Tabel pencocokan menyediakan mekanisme pencarian untuk nilai mentah yang terdapat dalam file transfer data, sehingga Anda dapat mencocokkan informasi penayangan iklan (seperti unit iklan atau item baris) untuk nilai yang telah ditetapkan sebelumnya dan tersimpan di database.

Jika Anda menjalankan laporan melalui ReportService atau dengan Transfer Data yang sama, sebaiknya lengkapi data laporan Anda dengan kolom. Misalnya, dengan laporan yang memiliki dimensi LINE_ITEM_ID atau dengan peristiwa transfer data yang memiliki kolom LineItemId, Anda dapat membuat tabel pencocokan yang menyertakan tanggal mulai tiap item baris, tanggal akhir, jenis, status, dan atribut berguna lainnya.

Ada beberapa cara untuk melakukan fungsi pencocokan ini:

  1. Gunakan tabel pencocokan siap pakai yang disediakan oleh BigQuery Data Transfer Service. Perhatikan bahwa tabel pencocokan ini tidak berisi setiap kolom entity.
  2. Pendekatan yang efisien adalah dengan menggunakan layanan PublisherQueryLanguageService tabel.
  3. Jika tidak ada tabel BigQuery atau PQL untuk entity, atau tabel tersebut tidak memiliki kolom yang Anda perlukan, Anda dapat memeriksanya layanan entity secara langsung, seperti OrderService.

Python

Menyiapkan kueri laporan

Mulailah dengan membuat tugas laporan, yang menentukan parameter laporan seperti dimensi, kolom, dan rentang tanggal.

# 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
    }
}

Download laporannya

# Initialize a DataDownloader.
report_downloader = client.GetDataDownloader(version='v202508')

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)

Mendownload data dari tabel PQL Line_Item

Untuk mencocokkan laporan dengan data item baris tambahan, Anda dapat menggunakan atribut 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)

Menggabungkan data laporan dengan data item baris

Contoh ini menggunakan library pandas karena mempermudah penggunaan data tabel. Di sini, fungsi ini digunakan untuk menggabungkan data laporan dengan data PQL untuk membuat tabel kecocokan.

# 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)
 Lihat di GitHub