許多應用程式的文件已依實體位置建立索引。例如，您的應用程式可能會讓使用者瀏覽目前位置附近的商店。
解決方案：Geohashes
Geohash 是一種系統，用來將 (latitude, longitude) 組合編碼為單一 Base32 字串。在 Geohash 系統中，世界會劃分成矩形網格。Geohash 字串的每個字元都會指定 32 個前置字串雜湊的子部分。舉例來說，Geohash abcd 是其中一個 32 個字元的雜湊值，包含在較大的 Geohash abc 中。
兩個雜湊之間的共用前置字串越長，彼此之間的距離越近。舉例來說，abcdef 比 abcdff 更接近 abcdeg。但反向操作並不正確！但兩個區域可能非常接近，而 Geohashes 大不相同：
我們可以透過 Geohashes 在 Cloud Firestore 中的位置儲存和查詢文件，同時兼顧效率，同時只需要單一建立索引的欄位。
安裝輔助程式庫
建立及剖析 Geohashes 涉及一些棘手的數學，因此我們建立了輔助程式庫，可抽離 Android、Apple 和 Web 上最困難的部分：
Web
// 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
Web
// 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
Swift
注意：這項產品不適用於 watchOS 和 App Clip 目標。
// 將此加入 Podfile
「GeoFire/Utils」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'
儲存地磚
對於要依位置建立索引的每份文件，您需要儲存 Geohash 欄位：
Web
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
});Web
// 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(() => {
// ...
});Swift
注意：這項產品不適用於 watchOS 和 App Clip 目標。
// 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
我們可以利用 Geohash 欄位彙整一組查詢，並篩除一些誤報，藉此近似區域查詢：
Web
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);
}
}
}Web
// 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
// ...
});
Swift
注意：這項產品不適用於 watchOS 和 App Clip 目標。
// 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 進行的查詢並非完全相同，而且您必須在用戶端過濾掉偽陽性結果。這類額外讀取作業會增加應用程式的成本並增加延遲。
- 邊緣案例：這個查詢方法需要預估經度/緯度之間的距離。隨著點越接近北極或南極，此估計值的準確度就會降低，這表示 Geohash 查詢在極大緯度中會有較多偽陽性。