প্রকাশক কোয়েরি ভাষা (PQL) ডেভেলপার গাইড

PQL সিনট্যাক্স ও ব্যবহার

PQL হল অবজেক্ট কোয়েরি করার জন্য SQL-এর মতো ভাষা। 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 - ফলাফল সেটের অফসেট যেখান থেকে ভ্যালু ফেরানো শুরু হবে। ফলাফলের পৃষ্ঠাগুলি দেখতে এটি ব্যবহার করুন।

    উদাহরণ (৫১-১০০ ফলাফল দেখায়):
    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 - ওয়াইল্ডকার্ড স্ট্রিং ম্যাচিং ব্যবহার করে অবজেক্টের জন্য কোয়েরি করার সুবিধা দেয়। শতকরা চিহ্ন (%) শূন্য, এক বা একাধিক অক্ষরকে বোঝায়। ম্যাচ করা সার্চ স্ট্রিং এনক্লোজ করতে একটি পেয়ার ব্যবহার করুন।

    উদাহরণ: WHERE name LIKE 'foo %searchString% bar'
    WHERE name LIKE 'Aus%'

  • IS NULL - এটি আপনাকে এমন অবজেক্টের জন্য কোয়েরি করতে দেয় যার প্রপার্টি ভ্যালু নির্দিষ্ট করা নেই। এর ক্লাসিক উদাহরণ হল, রুট AdUnit-এর জন্য কোয়েরি করা, যার জন্য নাল পেরেন্ট আইডি সহ AdUnit-এর জন্য কোয়েরি করতে হয়।

    উদাহরণ: WHERE parentId IS NULL।

  • <bind variable> - আপনার PQL কোয়েরিতে হার্ড-কোডেড <value> মানের পরিবর্তে Value অবজেক্ট ব্যবহার করতে পারবেন। PQL-এ বাইন্ড ভেরিয়েবলকে স্পেস ছাড়া স্ট্রিং নাম দিয়ে উল্লেখ করা হয়, যা : (কোলন) দিয়ে শুরু হয়।

    উদাহরণ (একটি কোয়েরি তৈরি করে এবং হার্ড-কোডেড 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 Data Transfer Service-এর প্রদান করা আগে থেকে তৈরি ম্যাচ টেবিল ব্যবহার করুন। মনে রাখবেন যে এই ম্যাচ টেবিলে প্রতিটি এন্টিটি ফিল্ড থাকে না।
  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='v202608')

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-এ দেখুন