wherobots-catalog

Python interface to the Wherobots Havasu Catalog using SedonaDB.

Installation

SedonaDB and the wherobots-catalog Python package can both be installed from PyPI:

pip install "apache-sedona[db]" wherobots-catalog

Example

import sedona.db
import wherobots.catalog

sd = sedona.db.connect()
wbc = wherobots.catalog.login()

If running wherobots-catalog from a Wherobots Cloud notebook, your credentials will be automatically discovered. For local development, you may provide an API key to the login() function or via the WHEROBOTS_API_KEY environment variable.

You can use attributes or indexing to access catalogs, namespaces, and tables within your Wherobots catalog.

wbc.wherobots_open_data.overture_maps_foundation.places_place
# Identical to
# wbc["wherobots_open_data.overture_maps_foundation.places_place"]
# or
# wbc["wherobots_open_data"]["overture_maps_foundation"]["places_place"]

WherobotsTable(wherobots_open_data.overture_maps_foundation.places_place)
┌────────────────────────────┬───────────────────────────┬───┬─────────┬───────────────────────────┐
│             id             ┆          geometry         ┆ … ┆ version ┆            bbox           │
│            utf8            ┆          geometry         ┆   ┆  int32  ┆           struct          │
╞════════════════════════════╪═══════════════════════════╪═══╪═════════╪═══════════════════════════╡
│ 83dcaa85-1797-4c6b-ab20-9… ┆ POINT(-42.37905094 -22.2… ┆ … ┆      12 ┆ {xmin: -42.3790512084960… │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ cf49ef40-3ff7-4453-bc91-0… ┆ POINT(-42.38782842646311… ┆ … ┆       4 ┆ {xmin: -42.3878288269043… │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ 59c80e33-8ba8-47e0-87ad-e… ┆ POINT(-42.38525390625 -2… ┆ … ┆       9 ┆ {xmin: -42.38525390625, … │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ b529ab6b-8275-4302-a6b0-2… ┆ POINT(-42.38494 -22.2912… ┆ … ┆       1 ┆ {xmin: -42.3849411010742… │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ 4cc0eb56-4a0d-4d7d-b8ba-3… ┆ POINT(-42.38494 -22.2912… ┆ … ┆       2 ┆ {xmin: -42.3849411010742… │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ 8e7c8a1d-621a-4129-a2d6-2… ┆ POINT(-42.38494 -22.2912… ┆ … ┆       1 ┆ {xmin: -42.3849411010742… │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ 92a53c29-fb7c-42ab-bcaa-e… ┆ POINT(-42.385597229004 -… ┆ … ┆       2 ┆ {xmin: -42.3856010437011… │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ 561e3be0-3a01-4798-9b0c-7… ┆ POINT(-42.385940551758 -… ┆ … ┆       9 ┆ {xmin: -42.3859443664550… │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ 1eeb59dd-f32a-4666-afc1-6… ┆ POINT(-42.385811805725 -… ┆ … ┆       2 ┆ {xmin: -42.3858184814453… │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ 2fa3e1fb-09fe-47f0-bc23-b… ┆ POINT(-42.394223213196 -… ┆ … ┆       9 ┆ {xmin: -42.3942298889160… │
└────────────────────────────┴───────────────────────────┴───┴─────────┴───────────────────────────┘

Table objects are SedonaDB DataFrames, which provide methods for column selection, filtering, and collection to various formats.

places = wbc.wherobots_open_data.overture_maps_foundation.places_place
boston_bounds = sd.funcs.st_makeenvelope(-71.19, 42.22, -70.92, 42.40)
(
    places.filter(
        places.names["primary"].funcs.lower().funcs.contains("library"),
        places.geometry.geo.intersects(boston_bounds),
    )
    .select(name=places.names["primary"], geometry="geometry")
    .show(5)
)

┌─────────────────────────────────────────────────────────┬─────────────────────────────────┐
│                           name                          ┆             geometry            │
│                           utf8                          ┆             geometry            │
╞═════════════════════════════════════════════════════════╪═════════════════════════════════╡
│ Archbishop Iakovos Library and Learning Resource Center ┆ POINT(-71.12908543 42.31708149) │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Annenberg Library at Pine Manor College                 ┆ POINT(-71.15659546 42.32076095) │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Social Work Library                                     ┆ POINT(-71.16972113 42.33383808) │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Thomas P. O'Neill Jr. Library                           ┆ POINT(-71.169262 42.33612449)   │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Theology and Ministry Library                           ┆ POINT(-71.16362 42.34288)       │
└─────────────────────────────────────────────────────────┴─────────────────────────────────┘

To query your catalogs from your own SedonaDB context, register the catalog list with sd.register(wbc):

sd.register(wbc)
sd.sql("""
    SELECT names['primary'] AS name, geometry
    FROM wherobots_open_data.overture_maps_foundation.places_place
    WHERE contains(lower(names['primary']), 'library')
      AND ST_Intersects(
          geometry,
          ST_MakeEnvelope(-71.19, 42.22, -70.92, 42.40)
      )
""").show(5)

┌──────────────────────────────────────────────────┬─────────────────────────────────────────────┐
│                       name                       ┆                   geometry                  │
│                       utf8                       ┆                   geometry                  │
╞══════════════════════════════════════════════════╪═════════════════════════════════════════════╡
│ Dedham Public Library                            ┆ POINT(-71.1761276 42.24775988)              │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Norfolk Law Library                              ┆ POINT(-71.1757283 42.2493331)               │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ West Roxbury Branch of the Boston Public Library ┆ POINT(-71.15737399 42.28335741)             │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Endicott Library                                 ┆ POINT(-71.16093651597511 42.23993011383171) │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Dedham Library-Yendicott Branch                  ┆ POINT(-71.16129 42.24105)                   │
└──────────────────────────────────────────────────┴─────────────────────────────────────────────┘

Browsing, table operations, and catalog-node .sql() use a private SedonaDB context. Registering wbc makes the catalogs available to sd.sql() without sharing session defaults or locally created tables with that private context. You can register the same catalog list in more than one SedonaDB context; however, if you register multiple catalog lists into the same context, names from the most recently registered catalog take precedence.

Catalog-node .sql() resolves table names relative to the selected node, without requiring registration in your own context. This can be useful for ad-hoc queries within a specific node of the catalog.

places_namespace = wbc.wherobots_open_data.overture_maps_foundation
places_namespace.sql("""
    SELECT names['primary'] AS name, geometry
    FROM places_place
""").show(5)

┌──────────────────────────────────────┬───────────────────────────────────────────────┐
│                 name                 ┆                    geometry                   │
│                 utf8                 ┆                    geometry                   │
╞══════════════════════════════════════╪═══════════════════════════════════════════════╡
│ Hospedaria Rancho Ferreira           ┆ POINT(-42.37905094 -22.28527906)              │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Sao Jose Do Ribeirão Em Bomjardim Rj ┆ POINT(-42.38782842646311 -22.278430489228455) │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Costuraria Uniformes                 ┆ POINT(-42.38525390625 -22.28591967928)        │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ TÁ MARA                              ┆ POINT(-42.38494 -22.29129)                    │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ Click Empório                        ┆ POINT(-42.38494 -22.29129)                    │
└──────────────────────────────────────┴───────────────────────────────────────────────┘