पब्लिशर क्वेरी लैंग्वेज (PQL) डेवलपर की गाइड

PQL सिंटैक्स और उसका इस्तेमाल

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 - कई शर्तों को जोड़ता है, जिनमें से सिर्फ़ एक सही होनी चाहिए. अगर आपको किसी एक प्रॉपर्टी की कई वैल्यू में से किसी एक की जांच करनी है, तो 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 क्वेरी के साथ काम करती हैं. उदाहरण के लिए, जिन क्रिएटिव प्रॉपर्टी को फ़िल्टर किया जा सकता है उनमें 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 - इससे आप वाइल्डकार्ड स्ट्रिंग मैचिंग का इस्तेमाल करके, ऑब्जेक्ट के लिए क्वेरी कर सकते हैं. प्रतिशत का चिह्न (%) शून्य, एक या एक से ज़्यादा वर्णों को दिखाता है. जिस खोज स्ट्रिंग को मैच करना है उसे शामिल करने के लिए, किसी जोड़े का इस्तेमाल करें.

    उदाहरण: WHERE name LIKE 'foo %searchString% bar'
    WHERE name LIKE 'Aus%'

  • IS NULL - इससे आपको प्रॉपर्टी की तय नहीं की गई वैल्यू वाले ऑब्जेक्ट के लिए क्वेरी करने की सुविधा मिलती है. इसका क्लासिक उदाहरण, शून्य पैरंट आईडी वाले AdUnit के लिए क्वेरी करके, रूट AdUnit के लिए क्वेरी करना है.

    उदाहरण: WHERE parentId IS NULL.

  • <bind variable> - अपनी PQL क्वेरी में, हार्ड कोड की गई <value> वैल्यू की जगह Value ऑब्जेक्ट इस्तेमाल किए जा सकते हैं. बाइंड वैरिएबल को पीक्यूएल में बताया जाता है. इसके लिए, बिना स्पेस वाली स्ट्रिंग के नाम का इस्तेमाल किया जाता है. यह नाम : (कोलन) से शुरू होता है.

    उदाहरण (क्वेरी बनाता है और हार्ड कोड की गई 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 फ़ील्ड वाले डेटा ट्रांसफ़र इवेंट के साथ, ऐसी मैच टेबल बनाई जा सकती है जिसमें हर लाइन आइटम के शुरू होने की तारीख, खत्म होने की तारीख, टाइप, स्टेटस, और अन्य काम के एट्रिब्यूट शामिल हों.

इस मिलते-जुलते फ़ंक्शन को पूरा करने के कई तरीके हैं:

  1. पहले से मौजूद, मैच करने वाली टेबल का इस्तेमाल करें. ये टेबल, BigQuery डेटा ट्रांसफ़र सेवा उपलब्ध कराती हैं. ध्यान दें कि इन मैच टेबल में, हर इकाई का फ़ील्ड शामिल नहीं होता.
  2. इसका सबसे सही तरीका यह है कि आप किसी भी उपलब्ध PublisherQueryLanguageService टेबल का इस्तेमाल करें.
  3. अगर इकाई के लिए कोई 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 पर देखें