جستارها - Unity

پیش‌نیازها

1. در صورتی که با سرویس پایگاه‌داده آشنایی ندارید، به معرفی سرویس پایگاه‌داده مراجعه کنید.
2. در صورتی که هنوز در پنل توسعه‌دهنده خود تنظیمات لازم برای سرویس پایگاه‌داده خود را انجام نداده‌اید، به تنظیمات پنل مراجعه کنید.
3. در صورتی که هنوز SDK یونیتی را راه‌اندازی نکرده‌اید، به راه‌اندازی SDK بکتوری در یونیتی مراجعه کنید.
4. در صورتی که هنوز کار با اشیاء پایگاه داده را به کمک SDK یونیتی فرا نگرفته‌اید، به کار با اشیاء مراجعه کنید.

مقدمه

بعد از ذخیره کردن اشیاء در پایگاه داده، بسیار پیش می‌آید که بخواهید آنها را بازیابی کنید. عملیات بازیابی عموما با تعیین چندین شرط (Constraint) صورت می‌گیرد و ما اشیایی را می‌خواهیم که در این شروط صدق کنند. به مجموعه شروط تعیین شده برای یک عملیات بازیابی «جُستار» (Query) گفته می‌شود.

بکتوری برای ساخت Query کلاس BacktoryQuery را در اختیار شما می‌گذارد. به صورت معمول شما یک BacktoryQuery با اسم جدولی که می‌خواهید سطرهای آنرا بازیابی کنید می‌سازید، روی آن شرایطی اعمال می‌کنید و سپس با تابع FindInBackground لیست اشیایی را که در این جستار صدق می‌کنند، می‌گیرید.

جستارهای ساده

ساده‌ترین و معمول ترین حالت، حالتی است که ‌می‌خواهیم مقدار ستون خاصی از سطرهای جدول، با مقداری که در جستار تعیین می‌کنیم برابر باشد. مثلا از جدول “Note” در پایگاه داده، تمامی یادداشت‌هایی را می‌خواهیم که عنوانشان “Todo” است. برای این بازیابی کد زیر می‌تواند استفاده شود:

BacktoryQuery todoQuery = new BacktoryQuery("Note");
todoQuery = todoQuery.WhereEqualTo("title", "Todo");
todoQuery.FindInBackground(response => {
    if (response.Successful) {
        IList<BacktoryObject> todoNotes = response.Body;
        // foreach (BacktoryObject todo in todoNotes)
        //   todo.Get<string>("content")...

    } else {
    
    // see response.Message to know the cause of error

    }
});

دقت کنید که BacktoryObject یک شیء immutable (تغییرناپذیر) است. بنابراین، با اضافه کردن یک شرط به جستار در واقع شیء جدیدی ساخته شده و به عنوان خروجی متد بازگردانده می‌شود. در کد بالا این شیء جدید را ذخیره کرده‌ایم و تابع FindInBackground را روی شیء جدید صدا می‌زنیم.

شروط جستار

برای تعیین شرط روی محتوای یک ستون، BacktoryQuery توابع متنوعی را فراهم کرده که با کلمه “Where” شروع می‌شوند. در زیر به طور مثال چند مورد از صدا زدن این توابع آورده شده است:

BacktoryQuery query = new BacktoryQuery("Note");
query = query.WhereNotEqualTo("title", "shopping"); // all the notes with titles other than "shopping"
query = query.WhereGreaterThan("priority", 4);      // notes with priority more than 4

می‌توان تعداد نتایج یک جستار را محدود کرد:

query = query.Limit(5);  // limit the notes to at most 5 results

می‌توان به صورت زیر اولین نتایج جستار را صرف نظر کرد. این حرکت در صفحه‌صفحه کردن (pagination) مفید خواهد بود.

query = query.Skip(5); // skip the first 5 results

برای ستون‌هایی که قابل مرتب سازی هستند، می‌توان نتیجه را بر اساس آن ستون، صعودی (ascending) یا نزولی (descending)، مرتب کرد. به شکل زیر:

// Sorts the results in ascending order by the priority field
query = query.OrderBy("priority");
// Sorts the results in descending order by the priority field
query = query.OrderByDescending("priority");

اگر می‌خواهید مقدار ستون نتایج جزو لیستی از مقادیر مشخص باشد، به این صورت می‌توانید عمل کنید:

// notes whose color column’s value is one of the red, blue or yellow
query = query.WhereContainedIn("color", new List<string>{"red", "blue", "yellow"});

جستار روی ستون‌های لیستی

اگر یک ستون از جنس لیست است، می‌توانید در اعضای آن لیست جستجو کنید. فرض کنید هر یادداشت لیستی از سایر یادداشت‌ها را دارد که به آن‌ها پیشنیازی دارد. در این صورت، جستار زیر یادداشت‌هایی را برمی‌گرداند که در لیست پیشنیازیشان، یادداشت شماره 2 وجود دارد.

// notes that have dependency on the note with id of 2
query = query.WhereEqualTo("dependsOn", 2);

حال اگر بخواهیم یادداشت‌هایی که به یادداشت‌های ۱ و ۲ و ۷ پیش‌نیازی دارند، را بازیابی کنیم، به صورت زیر عمل می‌کنیم:

// notes that have dependency on the notes of 1, 2 and 7
query = query.WhereContainsAll("dependsOn", new List<int>{1, 2, 7});

گرفتن چند نمونه‌ی تصادفی از یک جستار

می‌توان تعدادی تصادفی از سطرهایی که در یک جستار صدق می‌کنند را برگرداند. به طور مثال فرض کنید که جدول یادداشت شامل ستون tags است و برخی از یادداشت‌ها را با برچسب خاطره (diary) نشان کرده‌اید و می‌خواهید هر روز یک خاطره‌ی تصادفی را به کاربر نشان دهید.

new BacktoryQuery("Note").WhereEqualTo("tags", "diary")
    .Sample(1).findInBackground(response => {
        if (response.Successful) {
            BacktoryObject randomDiary = response.Body[0];
            Debug.Log("Your daily memory is: \n"
                    + randomDiary.Get<string>("content"));
        } else {
            // see response.Message to know the cause of error
        }
    });

جستار روی ستون‌های رشته‌ای

چنانچه جنس ستون رشته باشد، می‌توانید شرط‌های خاصی را روی آن اعمال کنید. مثلا یادداشت‌هایی را میخواهید که عنوانشان با “Call” شروع می‌شود و محتوایشان شامل عبارت “number” است. در این صورت کد زیر خواسته‌ی شما را برآورده می‌کند:

query = query.WhereStartsWith("title", "Call");     // matches "Call Backtory", "Call of Duty",
                                            //      but doesn’t match "call me baby!"
query = query.WhereContains("content", "number");

دیتابیس بکتوری از regular expression پشتیبانی می‌کند و شما با استفاده از تابع WhereMatches می‌توانید شروط دلخواه خود را روی ستون‌های رشته‌ای اعمال کنید.

توجه: جستارهای حاوی شروط regular expression سنگین و کندتر از سایر جستارها هستند.

شمارگان نتیجه‌ی یک جستار (Count query)

مواقعی پیش می‌آید که شما تنها «تعداد» سطرهایی را می‌خواهید که در یک جستار صدق می‌کنند و نه «خود» سطرها را. به طور مثال، فرض کنید جدول یادداشت ستونی به اسم tags از جنس آرایه دارد و تعداد یادداشت‌هایی را می‌خواهید که برچسب «وظیفه» (task) خورده‌اند. بدین منظور، کدی مانند زیر را می‌توانید اجرا کنید:

new BacktoryQuery("Note").WhereEqualTo("tags", "task").CountInBackground(response => {
    if (response.Successful) {
        int count = response.Body;
        Debug.Log("You have " + count + " task to complete!");
    } else {
        // see response.Message to know the cause of error
    }
});

جستارهای ترکیبی

اگر بخواهید اشیایی را بیابید که در یکی از چندین جستار صدق می‌کنند، می‌توانید از تابع BacktoryQuery.Or استفاده کنید که لیستی از جستارها را گرفته و از ترکیب آنها یک جستار می‌سازد. دقت کنید که جستارها باید متعلق به یک جدول باشند. روی جستار ترکیبی می‌توانید با توابع Where مجددا شرط اعمال کنید، اما نمی‌توانید فیلترهای Limit، Skip و OrderBy را استفاده کنید.

BacktoryQuery highPriorityNotes = new BacktoryQuery("Note");
highPriorityNotes = highPriorityNotes.WhereGreaterThanOrEqualTo("priority", 5);
BacktoryQuery importantNotes = new BacktoryQuery("Note");
importantNotes = importantNotes.WhereContains("content", "important");
BacktoryQuery compoundImportantQuery =
        BacktoryQuery.Or(new List<BacktoryQuery>{highPriorityNotes, importantNotes});

compoundImportantQuery.FindInBackground(response => {
    if (response.Successful) {
        // response.Body is the list of objects having
        //          either priority of 5 and more,
        //          or content with "important" substring.
    } else
 {
        // see response.Message to know the cause of error
    }
});

گرفتن تمام سطر‌های جدول

اگر بخواهید تمام سطر‌های یک جدول را دریافت کنید کافی است یک شیء BacktoryQuery بسازید و بعد روی آن تابع FindInBackground را صدا بزنید. البته لازم است که دقت کنید که یک جستار به صورت پیش فرض تنها ۱۰۰ نتیجه را باز می‌گرداند ولی می‌توانید این مقدار را تا ۱۰۰۰ افزاش دهید. پس اگر تعداد داده‌های جدول شما بیش از ۱۰۰۰ بود باید با استفاده از Limit و Skip محدوده‌های خود را تعیین کنید و سطر‌های آن محدوده را دریافت نمایید.

BacktoryQuery query = new BacktoryQuery("Note");

query.FindInBackground(response => {
          if (response.Successful) {
              // response.Body is the list of all objects.
          } else {
          
    // see response.Message to know the cause of error

          }
      });