Panduan Developer Bahasa Kueri Penayang (PQL)

Sintaksis dan penggunaan PQL

PQL adalah bahasa seperti 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 di-escape secara otomatis saat digunakan dalam parameter pengikatan. Atau:

    • Untuk string dalam tanda kutip tunggal (apostrof), hilangkan apostrof tambahan dengan menulisnya sebagai pasangan tanda kutip tunggal.

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

Kata kunci (tidak peka huruf besar/kecil)

  • WHERE - Menunjukkan kumpulan nol atau beberapa kondisi, jika digabungkan dengan menggunakan frasa AND atau OR. Anda dapat memaketkan frasa AND atau OR dengan tanda kurung. Mengeksekusi kueri "" (string kosong) akan 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, hanya satu yang harus bernilai benar. Jika Anda ingin memeriksa ada beberapa nilai untuk satu properti, sebaiknya gunakan klausa IN.

    Contoh: WHERE width = 728 OR height = 90

  • AND - Menggabungkan beberapa kondisi yang semuanya harus dipenuhi menggunakan klausa AND.

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

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

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

  • LIMIT - Jumlah hasil yang akan ditampilkan. LIMIT juga dapat menyertakan <offset>, yaitu jumlah baris dari awal untuk mengimbangi kumpulan 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 dalam hasil yang ditetapkan 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 difilter, menggunakan PQL; Anda biasanya tidak dapat memfilter semua properti yang didukung oleh objek, jadi periksa daftar di bawah untuk melihat properti mana yang mendukung kueri PQL. Misalnya, properti materi iklan yang dapat Anda filter menurut menyertakan id, name, width, dan height.
  • <value> - Nilai string harus diberi tanda kutip dengan satu tanda kutip ('). Nilai angka dapat dikutip atau tidak dikutip. Karakter pengganti tidak didukung.
  • IN - Membandingkan nilai properti dengan setiap item dalam daftar; jika ada yang cocok, maka ini adalah kecocokan positif. Operator IN setara dengan banyak kueri =, satu untuk setiap nilai, yang digabungkan dengan OR. Nilai ditetapkan sebagai daftar nilai yang dipisahkan koma, yang diapit dalam tanda kurung: (a, b, c). Semua nilai dalam daftar akan dievaluasi.

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

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

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

  • LIKE - Memungkinkan Anda membuat kueri untuk 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 untuk objek dengan nilai properti yang tidak ditentukan. Contoh klasiknya adalah mengkueri AdUnit root dengan membuat kueri untuk AdUnit menggunakan ID induk null.

    Contoh: WHERE parentId IS NULL.

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

    Contoh (Membuat kueri dan memasukkan dua variabel sebagai pengganti nilai properti id dan status hard code):

    // 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);
  • Kolom DateTime - Anda dapat memfilter menurut tanggal dan waktu dengan 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) dengan nilai yang telah ditetapkan sebelumnya yang disimpan di database.

Jika Anda menjalankan laporan melalui ReportService atau dengan laporan Transfer Data, sebaiknya lengkapi data laporan dengan kolom tambahan. 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, tanggal akhir, jenis, status, dan atribut berguna lainnya dari setiap item baris.

Ada beberapa cara untuk mendapatkan fungsi pencocokan ini:

  1. Gunakan tabel pencocokan yang telah dibuat sebelumnya yang disediakan oleh BigQuery Data Transfer Service. Perhatikan bahwa tabel pencocokan ini tidak berisi semua kolom entity.
  2. Pendekatan yang efisien adalah menggunakan salah satu tabel PublisherQueryLanguageService yang tersedia.
  3. Jika tidak ada tabel BigQuery atau PQL untuk entitas, atau tabel tidak memiliki kolom yang dibutuhkan, Anda dapat membuka layanan entitas tersebut secara langsung, seperti OrderService.

Python

Menyiapkan kueri laporan

Mulai 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 laporan

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

Unduh data dari tabel PQL Line_Item

Untuk mencocokkan laporan dengan data item baris tambahan, Anda dapat menggunakan tabel PQL Line_Item.

# 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 memudahkan pengoperasian data tabel. Di sini, kata kunci ini digunakan untuk menggabungkan data laporan dengan data PQL untuk membuat tabel pencocokan.

# 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