Panduan Developer Bahasa Kueri Penayang (PQL)

Sintaksis dan penggunaan PQL

PQL adalah bahasa seperti SQL untuk membuat kueri objek. Sintaks PQL-nya adalah 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 diringkas 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 bind. Atau:

    • Untuk string dalam tanda kutip tunggal (apostrof), escape setiap apostrof tambahan dengan menuliskannya sebagai sepasang tanda kutip tunggal.

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

Kata kunci (tidak peka huruf besar/kecil)

  • WHERE - Menunjukkan kumpulan nol atau beberapa kondisi, secara opsional digabungkan menggunakan frasa DAN atau ATAU. 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 - Bergabung dengan beberapa kondisi, hanya salah satunya harus 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 arahnya tidak nilai default-nya, 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 hasil set untuk memulai nilai yang ditampilkan. Gunakan ini untuk menelusuri hasil.

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

  • <property> - Salah satu properti yang diekspos oleh . 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 diberi tanda kutip dengan tanda kutip tunggal ('). Nilai angka dapat diberi tanda kutip atau tidak diberi tanda kutip. Karakter pengganti tidak didukung.
  • IN - Membandingkan nilai properti dengan setiap item dalam {i>list<i}; jika ada yang cocok, itu adalah kecocokan positif. IN operator setara dengan banyak kueri =, satu untuk setiap nilai, yang di-ORkan bersama-sama. 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. NOT IN operator setara dengan banyak kueri !=, satu untuk setiap nilai, yang di-ORkan bersama-sama. 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 untuk objek menggunakan karakter pengganti pencocokan string. 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 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. Pemberkasan variabel dirujuk dalam PQL menggunakan nama string tanpa spasi, dimulai dengan : (titik dua).

    Contoh (Membuat kueri dan memasukkan dua variabel sebagai pengganti properti id dan status yang di-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);
  • 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 entitas.
  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 butuhkan, Anda dapat memeriksanya layanan entity secara langsung, seperti OrderService.

Python

Menyiapkan kueri laporan

Mulai dengan membuat tugas laporan, dengan menentukan parameter laporan Anda 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='v202408')

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 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 pandas {i>library<i} karena membuat pekerjaan dengan data tabulasi menjadi jauh lebih mudah. Di sini, 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