docs: crs tracking example

[MrPowers]

I'm trying to demonstrate how SedonaDB tracks CRSs and doesn't allow for operations with mismatched CRSs.

Doesn't look like this code is properly setting the CRS:

cities = sd.sql("""
SELECT * FROM (VALUES
    ('New York', ST_SetSRID(ST_GeomFromText('POINT(-8238310.24 4969803.34)'), 3857)),
    ('Los Angeles', ST_SetSRID(ST_GeomFromText('POINT(-13153204.78 4037636.04)'), 3857)),
    ('Chicago', ST_SetSRID(ST_GeomFromText('POINT(-9757148.04 5138517.44)'), 3857)))
AS t(city, geometry)""")

cities.schema
SedonaSchema with 2 fields:
  city: Utf8
  geometry: Binary

Let me know if you have any suggestions on how to fix the code!

[paleolimbot]

Let me know if you have any suggestions on how to fix the code!

I believe this is caused by a DataFusion bug (all extension information in a VALUES clause are dropped). You should be able to work around this by moving the function call to the SELECT (also shorter!).

cities = sd.sql("""
SELECT city, ST_SetSRID(ST_GeomFromText(wkt), 3857) AS geometry FROM (VALUES
    ('New York', 'POINT(-8238310.24 4969803.34)'),
    ('Los Angeles', 'POINT(-13153204.78 4037636.04)'),
    ('Chicago', POINT(-9757148.04 5138517.44)'))
AS t(city, wkt)""")

[Copilot]

Pull Request Overview

This PR creates a Jupyter notebook demonstrating CRS (Coordinate Reference System) tracking in SedonaDB, specifically showing how mismatched CRSs prevent spatial operations and how to resolve them through transformation.

Key changes:

• Creates comprehensive CRS tracking examples showing error handling for mismatched CRSs
• Demonstrates proper CRS conversion using ST_Transform for successful spatial joins
• Shows real-world scenarios with different data sources (Parquet files, inline SQL data)

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Missing article before 'EPSG'. Should be 'an EPSG 4326 CRS' instead of 'a EPSG 4326 CRS'.

Suggested change

	"This example demonstrates how one table with a EPSG 4326 CRS cannot be joined with another table that uses EPSG 3857."
	"This example demonstrates how one table with an EPSG 4326 CRS cannot be joined with another table that uses EPSG 3857."

[MrPowers]

Updated

[Copilot]

This section header mentions 'different CRSs' but both tables (vermont and buildings) actually have compatible CRSs (epsg:4326 and ogc:crs84). The example should clarify that these CRSs are compatible or demonstrate an actual CRS mismatch scenario.

Suggested change

	"## Example #2: Joining two tables with different CRSs"
	"## Example #2: Joining two tables with nominally different but compatible CRSs\n",
	"\n",
	"In this example, we join two tables where one uses EPSG:4326 and the other uses OGC:CRS84. Although these CRSs are named differently, they are functionally equivalent, so the join works as expected. This demonstrates that not all differently-named CRSs are incompatible."

[MrPowers]

Not relevant anymore, but smart observation

[paleolimbot]

Great!

docs/crs-examples.md needs to be added to the navigation in mkdocs.yml somewhere or I don't think it will be accessible.

You can render with ci/scripts/build-docs.sh. We currently include both the .md and .ipynb files for the other guides (although strictly speaking we could gitignore them).

[kadolor]

This abbreviation should be defined once in the title and once in the regular text and before being used.

Suggested change

	"# CRS Examples\n",
	"# Coordinate Reference System (CRS) Examples\n",

[MrPowers]

Added this, thanks

[kadolor]

Suggested change

	"This example demonstrates how one table with a EPSG 4326 CRS cannot be joined with another table that uses EPSG 3857."
	"This example demonstrates how one table with a EPSG 4326 Coordinate Reference System (CRS) cannot be joined with another table that uses EPSG 3857."

[paleolimbot]

Looks good, although CI will fail until #108 is merged.

CI will also fail when this is merged if you don't add crs-examples.md to the navigation in mkdocs.yml.

[kadolor]

Looks good, although CI will fail until #108 is merged.

CI will also fail when this is merged if you don't add crs-examples.md to the navigation in mkdocs.yml.

Yes, please add this notebook to the mkdocs.yml @MrPowers