{
  "type": "h3-query",
  "description": "Named SQL source from an H3 dataset query.",
  "hasChildren": true,
  "propsSchema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
        "description": "Logical source name exposed to SQL widgets via {{name}}."
      },
      "endpoint": {
        "description": "Query endpoint speaking the /h3/query parameters: a full URL or a path relative to the current server root. Defaults to /h3/query. The viewer's token is sent only to the client's own server. Accepts a $param reference.",
        "type": "string"
      },
      "path": {
        "type": "string",
        "description": "Indexed H3 dataset location (as listed by GET /h3/datasets). Accepts a $param reference."
      },
      "cell": {
        "description": "Spatial selector: an H3 cell id as a hex string; rows filed under it or its descendants.",
        "type": "string"
      },
      "lat": {
        "description": "Spatial selector: point latitude (with lng).",
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string"
          }
        ]
      },
      "lng": {
        "description": "Spatial selector: point longitude (with lat).",
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string"
          }
        ]
      },
      "minLng": {
        "description": "Spatial selector: bounding box west edge.",
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string"
          }
        ]
      },
      "minLat": {
        "description": "Spatial selector: bounding box south edge.",
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string"
          }
        ]
      },
      "maxLng": {
        "description": "Spatial selector: bounding box east edge.",
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string"
          }
        ]
      },
      "maxLat": {
        "description": "Spatial selector: bounding box north edge.",
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string"
          }
        ]
      },
      "hexMin": {
        "description": "Spatial selector: raw H3 cell-id range start (hex string).",
        "type": "string"
      },
      "hexMax": {
        "description": "Spatial selector: raw H3 cell-id range end (hex string).",
        "type": "string"
      },
      "timeMin": {
        "description": "Inclusive ISO datetime; start of the time window.",
        "type": "string"
      },
      "timeMax": {
        "description": "Inclusive ISO datetime; end of the time window.",
        "type": "string"
      },
      "dateMin": {
        "description": "Alias of timeMin, as fused-hex sources name it.",
        "type": "string"
      },
      "dateMax": {
        "description": "Alias of timeMax, as fused-hex sources name it.",
        "type": "string"
      },
      "columns": {
        "description": "Columns to return; omitted means every column. An array, a comma-separated string, or a $param reference.",
        "anyOf": [
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          {
            "type": "string"
          }
        ]
      },
      "variables": {
        "description": "Alias of columns, as fused-hex sources name it.",
        "anyOf": [
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          {
            "type": "string"
          }
        ]
      },
      "partition": {
        "description": "Partition filter, keyed by partition column: {\"scenario\": [\"ssp245\", \"ssp585\"], \"date\": \"2050-01\"}.",
        "anyOf": [
          {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          },
          {
            "type": "string"
          }
        ]
      },
      "partitionRange": {
        "description": "Partition range filter, keyed by partition column: {\"date\": [\"2050-01\", \"2050-06\"]}; null for an open end.",
        "anyOf": [
          {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          },
          {
            "type": "string"
          }
        ]
      },
      "maxRowGroups": {
        "description": "Most row groups the server reads per page (server default 1024, max 4096).",
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string"
          }
        ]
      },
      "maxPages": {
        "default": 16,
        "description": "Most pages the widget follows before giving up. Defaults to 16; every page is held in browser memory.",
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "required": [
      "name",
      "path"
    ],
    "description": "Runs one GET /h3/query against an indexed H3 dataset, lands the Parquet result in DuckDB and exposes it as a named SQL source. Any SQL widget in reach of this node (the same node, or one connected by an edge) references the result via {{name}}; children are rendered as given. Every string or number prop accepts a $param reference (\"$lat\") or inline text (\"$year-01-01\"); the query waits until every referenced parameter has a value and re-runs when one changes. At most one spatial selector: cell, lat+lng, the four bounding box edges, or hexMin+hexMax; none reads the whole dataset.\n\n## Example\n\n```json\n{\n  \"type\": \"h3-query\",\n  \"props\": {\n    \"name\": \"era5_cells\",\n    \"path\": \"s3://fused-asset/data/era5/daily/\",\n    \"minLng\": -122.6, \"minLat\": 37.6, \"maxLng\": -122.2, \"maxLat\": 37.9,\n    \"timeMin\": \"$date_min\", \"timeMax\": \"$date_max\",\n    \"columns\": [\"hex\", \"date\", \"t2m\"]\n  },\n  \"children\": [\n    { \"type\": \"sql-table\", \"props\": { \"sql\": \"SELECT hex, AVG(t2m) AS t2m FROM {{era5_cells}} GROUP BY 1\" } }\n  ]\n}\n```"
  }
}