แอพจำนวนมากมีเอกสารที่ได้รับการจัดทำดัชนีตามสถานที่ตั้งทางกายภาพ ตัวอย่างเช่น แอปของคุณอาจอนุญาตให้ผู้ใช้เรียกดูร้านค้าใกล้ตำแหน่งปัจจุบันของตนได้
Cloud Firestore อนุญาตเพียง ส่วนคำสั่งช่วงเดียวต่อการค้นหาแบบผสม ซึ่งหมายความว่าเราไม่สามารถดำเนินการค้นหาทางภูมิศาสตร์โดยเพียงแค่จัดเก็บละติจูดและลองจิจูดเป็นช่องแยกกันและค้นหากล่องขอบเขต
วิธีแก้ปัญหา: Geohashes
Geohash คือระบบสำหรับการเข้ารหัสคู่ (latitude, longitude)
ให้เป็นสตริง Base32 เดี่ยว ในระบบ Geohash โลกจะถูกแบ่งออกเป็นตารางสี่เหลี่ยม อักขระแต่ละตัวของสตริง Geohash ระบุหนึ่งใน 32 ส่วนย่อยของแฮชคำนำหน้า ตัวอย่างเช่น Geohash abcd
เป็นหนึ่งในแฮชสี่อักขระ 32 ตัวที่มีอยู่ใน Geohash abc
ที่ใหญ่กว่า
ยิ่งคำนำหน้าที่ใช้ร่วมกันระหว่างสองแฮชนานเท่าใด แฮชทั้งสองก็จะยิ่งอยู่ใกล้กันมากขึ้นเท่านั้น ตัวอย่างเช่น abcdef
อยู่ใกล้ abcdeg
มากกว่า abcdff
แต่ทว่ากลับไม่เป็นความจริง! พื้นที่สองแห่งอาจอยู่ใกล้กันมาก แต่มี Geohashes ที่แตกต่างกันมาก:
เราสามารถใช้ Geohashes เพื่อจัดเก็บและสืบค้นเอกสารตามตำแหน่งใน Cloud Firestore ได้อย่างมีประสิทธิภาพสมเหตุสมผล ในขณะที่ต้องการเพียงฟิลด์ที่จัดทำดัชนีเพียงฟิลด์เดียว
ติดตั้งไลบรารีตัวช่วย
การสร้างและแยกวิเคราะห์ Geohashes ต้องใช้คณิตศาสตร์ที่ซับซ้อน ดังนั้นเราจึงสร้างไลบรารีตัวช่วยเพื่อสรุปส่วนที่ยากที่สุดบน Android, Apple และเว็บ:
API แบบโมดูลาร์ของเว็บ
// Install from NPM. If you prefer to use a static .js file visit
// https://github.com/firebase/geofire-js/releases and download
// geofire-common.min.js from the latest version
npm install --save geofire-common
API เนมสเปซของเว็บ
// Install from NPM. If you prefer to use a static .js file visit
// https://github.com/firebase/geofire-js/releases and download
// geofire-common.min.js from the latest version
npm install --save geofire-common
สวิฟท์
Kotlin+KTX
// Add this to your app/build.gradle
implementation 'com.firebase:geofire-android-common:3.2.0'
Java
// Add this to your app/build.gradle
implementation 'com.firebase:geofire-android-common:3.1.0'
เก็บ Geohashes
สำหรับแต่ละเอกสารที่คุณต้องการจัดทำดัชนีตามสถานที่ คุณจะต้องจัดเก็บฟิลด์ Geohash:
API แบบโมดูลาร์ของเว็บ
import { doc, updateDoc } from 'firebase/firestore'; // Compute the GeoHash for a lat/lng point const lat = 51.5074; const lng = 0.1278; const hash = geofire.geohashForLocation([lat, lng]); // Add the hash and the lat/lng to the document. We will use the hash // for queries and the lat/lng for distance comparisons. const londonRef = doc(db, 'cities', 'LON'); await updateDoc(londonRef, { geohash: hash, lat: lat, lng: lng });
API เนมสเปซของเว็บ
// Compute the GeoHash for a lat/lng point const lat = 51.5074; const lng = 0.1278; const hash = geofire.geohashForLocation([lat, lng]); // Add the hash and the lat/lng to the document. We will use the hash // for queries and the lat/lng for distance comparisons. const londonRef = db.collection('cities').doc('LON'); londonRef.update({ geohash: hash, lat: lat, lng: lng }).then(() => { // ... });
สวิฟท์
// Compute the GeoHash for a lat/lng point let latitude = 51.5074 let longitude = 0.12780 let location = CLLocationCoordinate2D(latitude: latitude, longitude: longitude) let hash = GFUtils.geoHash(forLocation: location) // Add the hash and the lat/lng to the document. We will use the hash // for queries and the lat/lng for distance comparisons. let documentData: [String: Any] = [ "geohash": hash, "lat": latitude, "lng": longitude ] let londonRef = db.collection("cities").document("LON") londonRef.updateData(documentData) { error in // ... }
Kotlin+KTX
// Compute the GeoHash for a lat/lng point val lat = 51.5074 val lng = 0.1278 val hash = GeoFireUtils.getGeoHashForLocation(GeoLocation(lat, lng)) // Add the hash and the lat/lng to the document. We will use the hash // for queries and the lat/lng for distance comparisons. val updates: MutableMap<String, Any> = mutableMapOf( "geohash" to hash, "lat" to lat, "lng" to lng, ) val londonRef = db.collection("cities").document("LON") londonRef.update(updates) .addOnCompleteListener { // ... }
Java
// Compute the GeoHash for a lat/lng point double lat = 51.5074; double lng = 0.1278; String hash = GeoFireUtils.getGeoHashForLocation(new GeoLocation(lat, lng)); // Add the hash and the lat/lng to the document. We will use the hash // for queries and the lat/lng for distance comparisons. Map<String, Object> updates = new HashMap<>(); updates.put("geohash", hash); updates.put("lat", lat); updates.put("lng", lng); DocumentReference londonRef = db.collection("cities").document("LON"); londonRef.update(updates) .addOnCompleteListener(new OnCompleteListener<Void>() { @Override public void onComplete(@NonNull Task<Void> task) { // ... } });
สอบถาม Geohashes
Geohashes ช่วยให้เราสามารถประมาณคำค้นหาในพื้นที่โดยการรวมชุดคำค้นหาในช่อง Geohash แล้วกรองผลบวกลวงออก:
API แบบโมดูลาร์ของเว็บ
import { collection, query, orderBy, startAt, endAt, getDocs } from 'firebase/firestore'; // Find cities within 50km of London const center = [51.5074, 0.1278]; const radiusInM = 50 * 1000; // Each item in 'bounds' represents a startAt/endAt pair. We have to issue // a separate query for each pair. There can be up to 9 pairs of bounds // depending on overlap, but in most cases there are 4. const bounds = geofire.geohashQueryBounds(center, radiusInM); const promises = []; for (const b of bounds) { const q = query( collection(db, 'cities'), orderBy('geohash'), startAt(b[0]), endAt(b[1])); promises.push(getDocs(q)); } // Collect all the query results together into a single list const snapshots = await Promise.all(promises); const matchingDocs = []; for (const snap of snapshots) { for (const doc of snap.docs) { const lat = doc.get('lat'); const lng = doc.get('lng'); // We have to filter out a few false positives due to GeoHash // accuracy, but most will match const distanceInKm = geofire.distanceBetween([lat, lng], center); const distanceInM = distanceInKm * 1000; if (distanceInM <= radiusInM) { matchingDocs.push(doc); } } }
API เนมสเปซของเว็บ
// Find cities within 50km of London const center = [51.5074, 0.1278]; const radiusInM = 50 * 1000; // Each item in 'bounds' represents a startAt/endAt pair. We have to issue // a separate query for each pair. There can be up to 9 pairs of bounds // depending on overlap, but in most cases there are 4. const bounds = geofire.geohashQueryBounds(center, radiusInM); const promises = []; for (const b of bounds) { const q = db.collection('cities') .orderBy('geohash') .startAt(b[0]) .endAt(b[1]); promises.push(q.get()); } // Collect all the query results together into a single list Promise.all(promises).then((snapshots) => { const matchingDocs = []; for (const snap of snapshots) { for (const doc of snap.docs) { const lat = doc.get('lat'); const lng = doc.get('lng'); // We have to filter out a few false positives due to GeoHash // accuracy, but most will match const distanceInKm = geofire.distanceBetween([lat, lng], center); const distanceInM = distanceInKm * 1000; if (distanceInM <= radiusInM) { matchingDocs.push(doc); } } } return matchingDocs; }).then((matchingDocs) => { // Process the matching documents // ... });
สวิฟท์
// Find cities within 50km of London let center = CLLocationCoordinate2D(latitude: 51.5074, longitude: 0.1278) let radiusInM: Double = 50 * 1000 // Each item in 'bounds' represents a startAt/endAt pair. We have to issue // a separate query for each pair. There can be up to 9 pairs of bounds // depending on overlap, but in most cases there are 4. let queryBounds = GFUtils.queryBounds(forLocation: center, withRadius: radiusInM) let queries = queryBounds.map { bound -> Query in return db.collection("cities") .order(by: "geohash") .start(at: [bound.startValue]) .end(at: [bound.endValue]) } @Sendable func fetchMatchingDocs(from query: Query, center: CLLocationCoordinate2D, radiusInMeters: Double) async throws -> [QueryDocumentSnapshot] { let snapshot = try await query.getDocuments() // Collect all the query results together into a single list return snapshot.documents.filter { document in let lat = document.data()["lat"] as? Double ?? 0 let lng = document.data()["lng"] as? Double ?? 0 let coordinates = CLLocation(latitude: lat, longitude: lng) let centerPoint = CLLocation(latitude: center.latitude, longitude: center.longitude) // We have to filter out a few false positives due to GeoHash accuracy, but // most will match let distance = GFUtils.distance(from: centerPoint, to: coordinates) return distance <= radiusInM } } // After all callbacks have executed, matchingDocs contains the result. Note that this code // executes all queries serially, which may not be optimal for performance. do { let matchingDocs = try await withThrowingTaskGroup(of: [QueryDocumentSnapshot].self) { group -> [QueryDocumentSnapshot] in for query in queries { group.addTask { try await fetchMatchingDocs(from: query, center: center, radiusInMeters: radiusInM) } } var matchingDocs = [QueryDocumentSnapshot]() for try await documents in group { matchingDocs.append(contentsOf: documents) } return matchingDocs } print("Docs matching geoquery: \(matchingDocs)") } catch { print("Unable to fetch snapshot data. \(error)") }
Kotlin+KTX
// Find cities within 50km of London val center = GeoLocation(51.5074, 0.1278) val radiusInM = 50.0 * 1000.0 // Each item in 'bounds' represents a startAt/endAt pair. We have to issue // a separate query for each pair. There can be up to 9 pairs of bounds // depending on overlap, but in most cases there are 4. val bounds = GeoFireUtils.getGeoHashQueryBounds(center, radiusInM) val tasks: MutableList<Task<QuerySnapshot>> = ArrayList() for (b in bounds) { val q = db.collection("cities") .orderBy("geohash") .startAt(b.startHash) .endAt(b.endHash) tasks.add(q.get()) } // Collect all the query results together into a single list Tasks.whenAllComplete(tasks) .addOnCompleteListener { val matchingDocs: MutableList<DocumentSnapshot> = ArrayList() for (task in tasks) { val snap = task.result for (doc in snap!!.documents) { val lat = doc.getDouble("lat")!! val lng = doc.getDouble("lng")!! // We have to filter out a few false positives due to GeoHash // accuracy, but most will match val docLocation = GeoLocation(lat, lng) val distanceInM = GeoFireUtils.getDistanceBetween(docLocation, center) if (distanceInM <= radiusInM) { matchingDocs.add(doc) } } } // matchingDocs contains the results // ... }
Java
// Find cities within 50km of London final GeoLocation center = new GeoLocation(51.5074, 0.1278); final double radiusInM = 50 * 1000; // Each item in 'bounds' represents a startAt/endAt pair. We have to issue // a separate query for each pair. There can be up to 9 pairs of bounds // depending on overlap, but in most cases there are 4. List<GeoQueryBounds> bounds = GeoFireUtils.getGeoHashQueryBounds(center, radiusInM); final List<Task<QuerySnapshot>> tasks = new ArrayList<>(); for (GeoQueryBounds b : bounds) { Query q = db.collection("cities") .orderBy("geohash") .startAt(b.startHash) .endAt(b.endHash); tasks.add(q.get()); } // Collect all the query results together into a single list Tasks.whenAllComplete(tasks) .addOnCompleteListener(new OnCompleteListener<List<Task<?>>>() { @Override public void onComplete(@NonNull Task<List<Task<?>>> t) { List<DocumentSnapshot> matchingDocs = new ArrayList<>(); for (Task<QuerySnapshot> task : tasks) { QuerySnapshot snap = task.getResult(); for (DocumentSnapshot doc : snap.getDocuments()) { double lat = doc.getDouble("lat"); double lng = doc.getDouble("lng"); // We have to filter out a few false positives due to GeoHash // accuracy, but most will match GeoLocation docLocation = new GeoLocation(lat, lng); double distanceInM = GeoFireUtils.getDistanceBetween(docLocation, center); if (distanceInM <= radiusInM) { matchingDocs.add(doc); } } } // matchingDocs contains the results // ... } });
ข้อจำกัด
การใช้ Geohashes สำหรับการสืบค้นตำแหน่งทำให้เรามีความสามารถใหม่ๆ แต่มาพร้อมกับข้อจำกัดของตัวเอง:
- ผลบวกลวง - การสืบค้นโดย Geohash นั้นไม่แม่นยำ และคุณต้องกรองผลลัพธ์ผลบวกลวงในฝั่งไคลเอ็นต์ออก การอ่านเพิ่มเติมเหล่านี้จะเพิ่มต้นทุนและเวลาในการตอบสนองให้กับแอปของคุณ
- Edge Cases - วิธีการสืบค้นนี้อาศัยการประมาณระยะห่างระหว่างเส้นลองจิจูด/ละติจูด ความแม่นยำของการประมาณการนี้จะลดลงเมื่อจุดเข้าใกล้ขั้วโลกเหนือหรือใต้มากขึ้น ซึ่งหมายความว่าข้อความค้นหา Geohash มีผลบวกลวงมากขึ้นที่ละติจูดสุดขีด