با مکاننماهای پُرسمان در Cloud Firestore، میتوانید دادههای برگرداندهشده توسط پُرسمان را براساس پارامترهایی که در پُرسمان تعریف میکنید به دستههایی تقسیم کنید.
مکاننماهای پُرسمان نقاط شروع و پایان پُرسمان را تعریف میکنند و به شما امکان میدهند:
- زیرمجموعهای از دادهها را برمیگرداند.
- صفحهبندی نتایج پُرسمان.
بااینحال، برای تعریف کردن محدودهای خاص برای پُرسمان، باید از روش where()
توضیحدادهشده در پُرسمانهای ساده استفاده کنید.
افزودن مکاننمای ساده به پُرسمان
از روشهای startAt() یا startAfter() برای تعریف نقطه شروع پُرسمان استفاده کنید.
روش startAt() شامل نقطه شروع است، درحالیکه روش startAfter() آن را مستثنی میکند.
برای مثال، اگر از startAt(A) در پُرسمان استفاده کنید، کل الفبا را برمیگرداند.
اگر درعوض از startAfter(A) استفاده کنید، B-Z را برمیگرداند.
Web
import { query, orderBy, startAt } from "firebase/firestore"; const q = query(citiesRef, orderBy("population"), startAt(1000000));
Web
citiesRef.orderBy("population").startAt(1000000);
Swift
// Get all cities with population over one million, ordered by population. db.collection("cities") .order(by: "population") .start(at: [1000000])
Objective-C
// Get all cities with population over one million, ordered by population. [[[db collectionWithPath:@"cities"] queryOrderedByField:@"population"] queryStartingAtValues:@[ @1000000 ]];
Kotlin
// Get all cities with a population >= 1,000,000, ordered by population, db.collection("cities") .orderBy("population") .startAt(1000000)
Java
// Get all cities with a population >= 1,000,000, ordered by population, db.collection("cities") .orderBy("population") .startAt(1000000);
Dart
db.collection("cities").orderBy("population").startAt([1000000]);
جاوا
پایتون
Python
C++
// Get all cities with a population >= 1,000,000, ordered by population, db->Collection("cities") .OrderBy("population") .StartAt({FieldValue::Integer(1000000)});
Node.js
رفتن
PHP
PHP
برای کسب اطلاعات بیشتر درباره نصب و ایجاد کارخواه Cloud Firestore، به کتابخانههای کارخواه Cloud Firestore مراجعه کنید.
Unity
Query query = citiesRef.OrderBy("Population").StartAt(1000000);
سی شارپ
Ruby
بهطور مشابه، از روشهای endAt() یا endBefore() برای تعریف نقطه پایان
برای نتایج پُرسمان خود استفاده کنید.
Web
import { query, orderBy, endAt } from "firebase/firestore"; const q = query(citiesRef, orderBy("population"), endAt(1000000));
Web
citiesRef.orderBy("population").endAt(1000000);
Swift
// Get all cities with population less than one million, ordered by population. db.collection("cities") .order(by: "population") .end(at: [1000000])
Objective-C
// Get all cities with population less than one million, ordered by population. [[[db collectionWithPath:@"cities"] queryOrderedByField:@"population"] queryEndingAtValues:@[ @1000000 ]];
Kotlin
// Get all cities with a population <= 1,000,000, ordered by population, db.collection("cities") .orderBy("population") .endAt(1000000)
Java
// Get all cities with a population <= 1,000,000, ordered by population, db.collection("cities") .orderBy("population") .endAt(1000000);
Dart
db.collection("cities").orderBy("population").endAt([1000000]);
جاوا
پایتون
Python
C++
// Get all cities with a population <= 1,000,000, ordered by population, db->Collection("cities") .OrderBy("population") .EndAt({FieldValue::Integer(1000000)});
Node.js
رفتن
PHP
PHP
برای کسب اطلاعات بیشتر درباره نصب و ایجاد کارخواه Cloud Firestore، به کتابخانههای کارخواه Cloud Firestore مراجعه کنید.
Unity
Query query = citiesRef.OrderBy("Population").EndAt(1000000);
سی شارپ
Ruby
استفاده از عکس آنی سند برای تعریف مکاننمای پُرسمان
همچنین میتوانید یک عکس آنی سند را بهعنوان نقطه شروع یا پایان مکاننمای پُرسمان به عبارت مکاننما ارسال کنید. مقادیر موجود در عکس آنی سند بهعنوان مقادیر موجود در مکاننمای پُرسمان عمل میکنند.
برای مثال، از سند «سان فرانسیسکو» در مجموعه دادههای شهرها و جمعیتها عکس آنی بگیرید. سپس، از آن عکس آنی سند بهعنوان نقطه شروع برای مکاننمای پُرسمان جمعیت استفاده کنید. پرسوجوی شما همه شهرهایی را که جمعیتشان بزرگتر یا مساوی با جمعیت سانفرانسیسکو است (همانطور که در عکس آنی سند تعریف شده است) برمیگرداند.
Web
import { collection, doc, getDoc, query, orderBy, startAt } from "firebase/firestore"; const citiesRef = collection(db, "cities"); const docSnap = await getDoc(doc(citiesRef, "SF")); // Get all cities with a population bigger than San Francisco const biggerThanSf = query(citiesRef, orderBy("population"), startAt(docSnap)); // ...
Web
var citiesRef = db.collection("cities"); return citiesRef.doc("SF").get().then((doc) => { // Get all cities with a population bigger than San Francisco var biggerThanSf = citiesRef .orderBy("population") .startAt(doc); // ... });
Swift
db.collection("cities") .document("SF") .addSnapshotListener { (document, error) in guard let document = document else { print("Error retreving cities: \(error.debugDescription)") return } // Get all cities with a population greater than or equal to San Francisco. let sfSizeOrBigger = db.collection("cities") .order(by: "population") .start(atDocument: document) }
Objective-C
[[[db collectionWithPath:@"cities"] documentWithPath:@"SF"] addSnapshotListener:^(FIRDocumentSnapshot *snapshot, NSError *error) { if (snapshot == nil) { NSLog(@"Error retreiving cities: %@", error); return; } // Get all cities with a population greater than or equal to San Francisco. FIRQuery *sfSizeOrBigger = [[[db collectionWithPath:@"cities"] queryOrderedByField:@"population"] queryStartingAtDocument:snapshot]; }];
Kotlin
// Get the data for "San Francisco" db.collection("cities").document("SF") .get() .addOnSuccessListener { documentSnapshot -> // Get all cities with a population bigger than San Francisco. val biggerThanSf = db.collection("cities") .orderBy("population") .startAt(documentSnapshot) // ... }
Java
// Get the data for "San Francisco" db.collection("cities").document("SF") .get() .addOnSuccessListener(new OnSuccessListener<DocumentSnapshot>() { @Override public void onSuccess(DocumentSnapshot documentSnapshot) { // Get all cities with a population bigger than San Francisco. Query biggerThanSf = db.collection("cities") .orderBy("population") .startAt(documentSnapshot); // ... } });
Dart
db.collection("cities").doc("SF").get().then( (documentSnapshot) { final biggerThanSf = db .collection("cities") .orderBy("population") .startAtDocument(documentSnapshot); }, onError: (e) => print("Error: $e"), );
جاوا
پایتون
Python
C++
db->Collection("cities").Document("SF").Get().OnCompletion( [db](const Future<DocumentSnapshot>& future) { if (future.error() == Error::kErrorOk) { const DocumentSnapshot& document_snapshot = *future.result(); Query bigger_than_sf = db->Collection("cities") .OrderBy("population") .StartAt({document_snapshot}); // ... } });
Node.js
رفتن
PHP
PHP
برای کسب اطلاعات بیشتر درباره نصب و ایجاد کارخواه Cloud Firestore، به کتابخانههای کارخواه Cloud Firestore مراجعه کنید.
Unity
CollectionReference citiesRef = db.Collection("cities"); DocumentReference docRef = citiesRef.Document("SF"); docRef.GetSnapshotAsync().ContinueWith((snapshotTask) => { Query query = citiesRef.OrderBy("Population").StartAt(snapshotTask.Result); });
سی شارپ
Ruby
صفحهبندی پرسمان
با ترکیب مکاننماهای پُرسمان با روش limit()، پُرسمانها را صفحهبندی کنید.
برای مثال، از آخرین سند در یک دسته بهعنوان شروع مکاننما برای دسته بعدی استفاده کنید.
Web
import { collection, query, orderBy, startAfter, limit, getDocs } from "firebase/firestore"; // Query the first page of docs const first = query(collection(db, "cities"), orderBy("population"), limit(25)); const documentSnapshots = await getDocs(first); // Get the last visible document const lastVisible = documentSnapshots.docs[documentSnapshots.docs.length-1]; console.log("last", lastVisible); // Construct a new query starting at this document, // get the next 25 cities. const next = query(collection(db, "cities"), orderBy("population"), startAfter(lastVisible), limit(25));
Web
var first = db.collection("cities") .orderBy("population") .limit(25); return first.get().then((documentSnapshots) => { // Get the last visible document var lastVisible = documentSnapshots.docs[documentSnapshots.docs.length-1]; console.log("last", lastVisible); // Construct a new query starting at this document, // get the next 25 cities. var next = db.collection("cities") .orderBy("population") .startAfter(lastVisible) .limit(25); });
Swift
// Construct query for first 25 cities, ordered by population let first = db.collection("cities") .order(by: "population") .limit(to: 25) first.addSnapshotListener { (snapshot, error) in guard let snapshot = snapshot else { print("Error retreving cities: \(error.debugDescription)") return } guard let lastSnapshot = snapshot.documents.last else { // The collection is empty. return } // Construct a new query starting after this document, // retrieving the next 25 cities. let next = db.collection("cities") .order(by: "population") .start(afterDocument: lastSnapshot) // Use the query for pagination. // ... }
Objective-C
FIRQuery *first = [[[db collectionWithPath:@"cities"] queryOrderedByField:@"population"] queryLimitedTo:25]; [first addSnapshotListener:^(FIRQuerySnapshot *snapshot, NSError *error) { if (snapshot == nil) { NSLog(@"Error retreiving cities: %@", error); return; } if (snapshot.documents.count == 0) { return; } FIRDocumentSnapshot *lastSnapshot = snapshot.documents.lastObject; // Construct a new query starting after this document, // retreiving the next 25 cities. FIRQuery *next = [[[db collectionWithPath:@"cities"] queryOrderedByField:@"population"] queryStartingAfterDocument:lastSnapshot]; // Use the query for pagination. // ... }];
Kotlin
// Construct query for first 25 cities, ordered by population val first = db.collection("cities") .orderBy("population") .limit(25) first.get() .addOnSuccessListener { documentSnapshots -> // ... // Get the last visible document val lastVisible = documentSnapshots.documents[documentSnapshots.size() - 1] // Construct a new query starting at this document, // get the next 25 cities. val next = db.collection("cities") .orderBy("population") .startAfter(lastVisible) .limit(25) // Use the query for pagination // ... }
Java
// Construct query for first 25 cities, ordered by population Query first = db.collection("cities") .orderBy("population") .limit(25); first.get() .addOnSuccessListener(new OnSuccessListener<QuerySnapshot>() { @Override public void onSuccess(QuerySnapshot documentSnapshots) { // ... // Get the last visible document DocumentSnapshot lastVisible = documentSnapshots.getDocuments() .get(documentSnapshots.size() -1); // Construct a new query starting at this document, // get the next 25 cities. Query next = db.collection("cities") .orderBy("population") .startAfter(lastVisible) .limit(25); // Use the query for pagination // ... } });
Dart
// Construct query for first 25 cities, ordered by population final first = db.collection("cities").orderBy("population").limit(25); first.get().then( (documentSnapshots) { // Get the last visible document final lastVisible = documentSnapshots.docs[documentSnapshots.size - 1]; // Construct a new query starting at this document, // get the next 25 cities. final next = db .collection("cities") .orderBy("population") .startAfterDocument(lastVisible) .limit(25); // Use the query for pagination // ... }, onError: (e) => print("Error completing: $e"), );
جاوا
پایتون
Python
C++
// Construct query for first 25 cities, ordered by population Query first = db->Collection("cities").OrderBy("population").Limit(25); first.Get().OnCompletion([db](const Future<QuerySnapshot>& future) { if (future.error() != Error::kErrorOk) { // Handle error... return; } // Get the last visible document const QuerySnapshot& document_snapshots = *future.result(); std::vector<DocumentSnapshot> documents = document_snapshots.documents(); const DocumentSnapshot& last_visible = documents.back(); // Construct a new query starting at this document, // get the next 25 cities. Query next = db->Collection("cities") .OrderBy("population") .StartAfter(last_visible) .Limit(25); // Use the query for pagination // ... });
Node.js
رفتن
PHP
PHP
برای کسب اطلاعات بیشتر درباره نصب و ایجاد کارخواه Cloud Firestore، به کتابخانههای کارخواه Cloud Firestore مراجعه کنید.
Unity
CollectionReference citiesRef = db.Collection("cities"); Query firstQuery = citiesRef.OrderBy("Population").Limit(3); // Get the last document from the results firstQuery.GetSnapshotAsync().ContinueWith((querySnapshotTask) => { long lastPopulation = 0; foreach (DocumentSnapshot documentSnapshot in querySnapshotTask.Result.Documents) { lastPopulation = documentSnapshot.GetValue<long>("Population"); } // Construct a new query starting at this document. // Note: this will not have the desired effect if multiple cities have the exact same population value Query secondQuery = citiesRef.OrderBy("Population").StartAfter(lastPopulation); Task<QuerySnapshot> secondQuerySnapshot = secondQuery.GetSnapshotAsync();
سی شارپ
Ruby
تنظیم مکاننما براساس چند فیلد
وقتی از مکاننمایی براساس مقدار فیلد (نه DocumentSnapshot) استفاده میکنید، میتوانید با افزودن فیلدهای بیشتر، موقعیت مکاننما را دقیقتر کنید. این بهویژه زمانی مفید است که مجموعه دادههای شما شامل چندین سند باشد که همگی مقدار یکسانی برای فیلد مکاننما دارند، که باعث میشود موقعیت مکاننما مبهم باشد. میتوانید مقادیر فیلد بیشتری به مکاننما اضافه کنید تا نقطه شروع یا پایان را بیشتر مشخص کنید و ابهام را کاهش دهید.
برای مثال، در مجموعه دادهای که حاوی همه شهرهایی است که نامشان «Springfield» در ایالات متحده است، چندین نقطه شروع برای پُرسمانی وجود دارد که تنظیم شده است از «Springfield» شروع شود:
| شهرها | |
|---|---|
| نام | ایالت |
| اسپرینگفیلد | ماساچوست |
| اسپرینگفیلد | میسوری |
| اسپرینگفیلد | ویسکانسین |
برای شروع از یک اسپرینگفیلد خاص، میتوانید ایالت را بهعنوان شرط ثانویه در عبارت مکاننما اضافه کنید.
Web
// Will return all Springfields import { collection, query, orderBy, startAt } from "firebase/firestore"; const q1 = query(collection(db, "cities"), orderBy("name"), orderBy("state"), startAt("Springfield")); // Will return "Springfield, Missouri" and "Springfield, Wisconsin" const q2 = query(collection(db, "cities"), orderBy("name"), orderBy("state"), startAt("Springfield", "Missouri"));
Web
// Will return all Springfields db.collection("cities") .orderBy("name") .orderBy("state") .startAt("Springfield"); // Will return "Springfield, Missouri" and "Springfield, Wisconsin" db.collection("cities") .orderBy("name") .orderBy("state") .startAt("Springfield", "Missouri");
Swift
// Will return all Springfields db.collection("cities") .order(by: "name") .order(by: "state") .start(at: ["Springfield"]) // Will return "Springfield, Missouri" and "Springfield, Wisconsin" db.collection("cities") .order(by: "name") .order(by: "state") .start(at: ["Springfield", "Missouri"])
Objective-C
// Will return all Springfields [[[[db collectionWithPath:@"cities"] queryOrderedByField:@"name"] queryOrderedByField:@"state"] queryStartingAtValues:@[ @"Springfield" ]]; // Will return "Springfield, Missouri" and "Springfield, Wisconsin" [[[[db collectionWithPath:@"cities"] queryOrderedByField:@"name"] queryOrderedByField:@"state"] queryStartingAtValues:@[ @"Springfield", @"Missouri" ]];
Kotlin
// Will return all Springfields db.collection("cities") .orderBy("name") .orderBy("state") .startAt("Springfield") // Will return "Springfield, Missouri" and "Springfield, Wisconsin" db.collection("cities") .orderBy("name") .orderBy("state") .startAt("Springfield", "Missouri")
Java
// Will return all Springfields db.collection("cities") .orderBy("name") .orderBy("state") .startAt("Springfield"); // Will return "Springfield, Missouri" and "Springfield, Wisconsin" db.collection("cities") .orderBy("name") .orderBy("state") .startAt("Springfield", "Missouri");
Dart
// Will return all Springfields db .collection("cities") .orderBy("name") .orderBy("state") .startAt(["Springfield"]); // Will return "Springfield, Missouri" and "Springfield, Wisconsin" db .collection("cities") .orderBy("name") .orderBy("state") .startAt(["Springfield", "Missouri"]);
جاوا
پایتون
Python
C++
// This is not yet supported.Node.js
رفتن
PHP
PHP
برای کسب اطلاعات بیشتر درباره نصب و ایجاد کارخواه Cloud Firestore، به کتابخانههای کارخواه Cloud Firestore مراجعه کنید.
Unity
Query query1 = db.Collection("cities").OrderBy("Name").OrderBy("State").StartAt("Springfield"); Query query2 = db.Collection("cities").OrderBy("Name").OrderBy("State").StartAt("Springfield", "Missouri");