sedona-research

name	sedona-research
description	Research SedonaDB spatial functions before implementation. Use when you need to understand how a SedonaDB ST_* function works before implementing it in the sx R package. MANDATORY before implementing any new sx function.

SedonaDB Function Research Skill

Use this skill BEFORE implementing any SedonaDB function wrapper in the sx package. Research is MANDATORY - never implement without completing this workflow first.

Critical principle

Source of Truth is Distributed. SedonaDB function behavior is defined across multiple sources:

1. SQL Docs define the intended user API
2. Rust Source defines the actual arguments, types, and validation
3. Python Tests reveal edge cases and expected behavior

NEVER guess argument types, availability, or behavior.

Research workflow

1. SQL Documentation scan

Source: .sync/sedona-db/docs/reference/sql.md

Search for the function and extract:

• Function name and description
• Since: vX.Y version
• Format/signature (e.g., ST_Buffer(A: Geometry, distance: Double))
• Arguments list with types
• SQL example

2. Rust registration check

Source: .sync/sedona-db/rust/sedona-functions/src/register.rs

Search for the function in register_scalar_udfs! or register_aggregate_udfs!:

• Confirm function is registered (e.g., crate::st_buffer::st_buffer_udf)
• Note if it's scalar vs aggregate

If not found in register.rs, the function is NOT available to the SQL engine.

3. Rust signature verification

Source: .sync/sedona-db/rust/sedona-functions/src/st_{function}.rs

Look for ArgMatcher::new() and document:

• Exact argument types:
  • ArgMatcher::is_geometry_or_geography() - accepts Geometry or Geography
  • ArgMatcher::is_geometry() - accepts only Geometry
  • ArgMatcher::is_numeric() - accepts doubles/integers
  • ArgMatcher::is_text() - accepts strings
  • ArgMatcher::is_optional() - optional argument
• Return type (usually in WKB_GEOMETRY or DataType::Float64)
• Volatility (Immutable, Stable, Volatile)
• Any special validation or error conditions

4. Python test review

Source: .sync/sedona-db/python/sedonadb/tests/functions/

Search for test cases in test_functions.py, test_predicates.py, or similar:

• Normal input examples
• NULL handling behavior
• Empty geometry handling
• Edge cases

5. R ecosystem check

Source: sf package documentation for the equivalent function (e.g., ?sf::st_buffer)

Compare:

• Parameter names and order
• Default values
• sf-specific parameters that SedonaDB doesn't support
• Return value differences

6. Document findings

Create .claude/research/sedona/{function_name}.md:

# ST_{FunctionName} Research

## Summary
[1-2 sentence description focused on sx wrapper implementation]

## SQL API
**Since:** vX.Y
**Signature:** `ST_Function(geom: Geometry, arg: Type)`

### Arguments
| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| geom | Geometry/Geography | Yes | Input geometry |
| arg | Double | Yes | Description |

### Return
- Type: Geometry
- NULL behavior: [describe]

## Rust Implementation
**File:** `st_{function}.rs`
**Registration:** `crate::st_{function}::st_{function}_udf`
**Volatility:** Immutable

### ArgMatcher
```rust
ArgMatcher::new(
    vec![
        ArgMatcher::is_geometry_or_geography(),
        ArgMatcher::is_numeric(),
    ],
    WKB_GEOMETRY,
)

sf Equivalent

Function: sf::st_function() Unsupported sf args: [list args sx should warn about] Key differences: [describe]

Edge Cases (from Python tests)

• NULL input returns NULL
• Empty geometry returns [describe]
• [other edge cases]

Implementation Notes

• [Any special considerations]
• [S2/Geography handling requirements]
• [CRS considerations]

Sources

• SQL Docs: .sync/sedona-db/docs/reference/sql.md (line ~XXX)
• Rust Impl: .sync/sedona-db/rust/sedona-functions/src/st_{function}.rs
• Python Tests: .sync/sedona-db/python/sedonadb/tests/functions/test_functions.py
• sf Docs: https://r-spatial.github.io/sf/reference/st_{function}.html

## Checklist

Before proceeding to implementation:

- [ ] Found function in SQL docs with version and signature
- [ ] Confirmed registration in `register.rs`
- [ ] Verified ArgMatcher types in Rust source
- [ ] Reviewed Python test cases for edge cases
- [ ] Compared with sf equivalent function
- [ ] Created research file at `.claude/research/sedona/{function_name}.md`
- [ ] Documented all sources with file paths/URLs

## What to do after research

Proceed to implementation using the `sedona-implement` skill.