Query Data

Overview

See Data section for how data is handled details.

Query

A query object is used in a query function to configure how data should be filtered and returned, for example as a GeoJSON string or as an array of objects. The function will query locally cached data received previously. It blocks the current thread, so using a separate background thread is required.

Each data type provides its configuration type and function to query. See the corresponding page of these docs for more details.

Query lifecycle

To ensure results are always accurate, Query instances are intended to be short lived.

• Always create a new Query right before calling data(with:).

Recommended pattern (fresh query per request):

func fetchData(...) {
    var query = OneLayerQuery(
        altRange: 0...52_000,
        resultOptions: .items,
        aggregate: false
    )
    query.nowcastEnabled = false

    let result = try? SkyPath.shared.data(with: query).get()
    // Process result
}

• Do not store a Query as a static property or any other long lived instance.
• Do not reuse a Query across multiple fetches.

Reusing a long lived Query can lead to outdated internal state (for example, time ranges or tiles), which may produce incorrect results.

Incorrect pattern (long lived query):

var oneLayerQuery: OneLayerQuery = {
    var query = OneLayerQuery(
        altRange: 0...52_000,
        resultOptions: .items,
        aggregate: false
    )
    query.nowcastEnabled = false
    return query
}()

or

static let oneLayerQuery: OneLayerQuery = {
    var query = OneLayerQuery(
        altRange: 0...52_000,
        resultOptions: .items,
        aggregate: false
    )
    query.nowcastEnabled = false
    return query
}()

All code samples should follow this pattern and create a fresh Query inline before calling data(with:).

A general illustration example of how to query data is as follows, where:

• data(with:) is a function in SkyPath to query data
• Query is a data query configuration
• result will be of a QueryResult<Item> type

do {
    let result = try SkyPath.shared.data(with: Query()).get()
    let geoJSON = result.geoJSON
    // Show GeoJSON on the map
} catch {
    print(error)
}

A query config can allow getting items for specific tiles using the tiles property. It accepts the h3 or h3-alt format. Such tile id can be taken from the tile property of an item object, which is a Tile object with the corresponding properties Tile.key and Tile.keyByCoord or Tile.h3Hex.

Result

The Query.resultOptions of the QueryResultOptions type determines in which format returns the queried data in a QueryResult object.

• items will provide an array of item objects. It can be used for postprocessing and converting for rendering in a custom way.

• geoJSON will generate a GeoJSON string to visualize on the map. It has a geometry polygon to draw the hexagons and extra properties for each one like severity and others. Please note that the properties fields could not match the item object fields as it's not equivalent objects.

• geoJSONData is the same as geoJSON just as Data not as String.

note

The GeoJSON string is not intended to provide all the details about each report. It is intended to have minimal details to visualize on the map. Item objects can be used to get all the details.

Item

The item object has all the details.

For example, when need to show report details by tapping on the report on the map, the GeoJSON feature properties could not have all the needed values. Also, it could be hard to find all reports in the tapped area using GeoJSON only.

Here is the flow:

1. When tapping the GeoJSON feature on the map, take the h3Hex string from the properties. It's the H3 index of the tapped hexagon.

2. Query data from the SDK in the tapped hexagon.

do {
    let query = Query(resultOptions: .items, aggregate: false, tiles: [h3Hex])
    let result = try SkyPath.shared.data(with: query).get()
    // Process `result.items`
} catch {
    print(error)
}