docs: GET /api/maps/preview-sources/:sourceId/field-values endpoint missing from behaviors.md

[evan-zhang11]

Problem

The field values endpoint GET /api/maps/preview-sources/:sourceId/field-values is implemented in backend/src/map_handlers.rs (handler get_field_values) and registered in backend/src/routes.rs, but is not documented in any behavior contract entry in docs/dev/behaviors.md.

Implementation Details

Route: GET /api/maps/preview-sources/{sourceId}/field-values

Query Parameters:

• field (required, string) — The field/column name to fetch values for
• limit (optional, integer, default: 50, max: 500) — Maximum number of distinct values to return

Authentication: Required

Behavior:

1. Looks up the file by sourceId in the current workspace
2. Returns 404 if source not found, 409 if not ready
3. Returns 400 if source has no import table (e.g., MBTiles) or is not a DuckDB source
4. For numeric fields (Int/Float/Double types):
   • Returns min/max statistics
   • Returns distinct values up to limit
   • Also returns sortedValues — all numeric values sorted (this is tracked as a bug in code-quality: get_field_values returns ALL numeric values as sorted_values regardless of limit parameter #363)
5. For non-numeric fields:
   • Returns distinct string values up to limit

Response (numeric):

{
  "field": "population",
  "values": [100, 200, 300],
  "type": "Double",
  "min": 0.0,
  "max": 999999.0,
  "sortedValues": [0.0, 1.5, 2.3, ...]
}

Response (non-numeric):

{
  "field": "name",
  "values": ["Alice", "Bob"],
  "type": "String"
}

Errors: 400 (empty field / non-DuckDB source), 401, 404, 409 (not ready)

Related Issues

• code-quality: get_field_values returns ALL numeric values as sorted_values regardless of limit parameter #363: sortedValues returns ALL values ignoring limit (code quality bug)
• performance: get_field_values loads entire numeric column into memory #351: Loads entire numeric column into memory (performance concern)

Proposed Action

Add a behavior contract entry (e.g., MAP-001 or API-023) documenting:

• Query parameters and their constraints
• Response schema for numeric vs non-numeric fields
• Error responses and status codes
• The field type detection logic (based on dataset_columns.mvt_type)

Priority: P2 — Endpoint is functional but has known performance issues (#351, #363). Documentation should note these as known limitations.