DataStore

public classDataStore

Persisted location record management — query, upload, and destroy stored locations.

Access via BGGeo.instance.store.

---

Members

all

public func all(limit: Int = 0, offset: Int = 0, page: Int = 0, order: Int = 0) async throws -> [[String: Any]]

Retrieve LocationEvent records stored in the SDK's SQLite database.

Provide an optional LocationQuery to page through a large table, constraining results by limit, starting offset (or page), and sort order. Without a query, every record is returned in a single call — which can exhaust memory on a table of several thousand records, so prefer paging for large datasets. Size your paging with BGGeo.getCount.

let bgGeo = BGGeo.shared
Task {
    do {
        // All records
        let locations = try await bgGeo.store.all()

        // One page of 500, newest first
        let page = try await bgGeo.store.all(limit: 500, page: 0, order: BGGeo.DataStore.ORDER_DESC)
    } catch {
        print("Error: \(error)")
    }
}

count

public var count: Int

Retrieve the count of all locations currently stored in the SDK's SQLite database.

let bgGeo = BGGeo.shared
let count = bgGeo.store.count

destroy

public func destroy(_ uuid: String)

Remove a single location by LocationEvent.uuid.

Resolves true once the record is removed.

let bgGeo = BGGeo.shared
let uuid = "some-location-uuid"
bgGeo.store.destroy(uuid)

destroyAll

public func destroyAll() async throws

Remove all records from the SDK's SQLite database.

Resolves true once the store is cleared, like the geofence mutators.

let bgGeo = BGGeo.shared
Task {
    do {
        try await bgGeo.store.destroyAll()
    } catch {
        print("Error: \(error)")
    }
}

insert

public func insert(_ params: [String: Any]) async throws -> String

Manually insert a location record into the SDK's SQLite database.

The record is stored as given — the SDK does not overwrite its timestamp, activity, is_moving, odometer, battery, or other fields with current device state. This is intended for importing history or externally-sourced fixes the SDK did not record itself. Only coords (latitude and longitude) is required; a missing or unparseable timestamp defaults to the current time. Resolves with the uuid of the inserted record — the SDK generates one when the caller does not supply a uuid.

Note

insertLocation deliberately bypasses PersistenceConfig.persistMode — an explicit insert always writes to the database, regardless of the configured persistence mode. For recording the device's own position on demand, prefer getCurrentPosition.

let bgGeo = BGGeo.shared
let uuid = try await bgGeo.store.insert([
  "timestamp": "2024-01-15T10:30:00.000Z",
  "coords": ["latitude": 45.5152, "longitude": -73.6104],
  "extras": ["source": "import"]
])
print("[insertLocation] inserted record: \(uuid)")

sync

public func sync() async throws -> [[String: Any]]

Manually upload all queued locations to HttpConfig.url.

Initiates a POST of all records in the SQLite database to your configured HttpConfig.url. Records that receive a 200 OK response are deleted from the database. If HttpConfig.batchSync is true, all locations are sent in a single request; otherwise one request is made per location. If no HTTP service is configured, all records are deleted from the database.

See also - HTTP Guide

let bgGeo = BGGeo.shared
Task {
    do {
        let records = try await bgGeo.store.sync()
        print("[sync] success: \(records)")
    } catch {
        print("[sync] FAILURE: \(error)")
    }
}