notex.nvim/specs/002-notex-is-a/contracts/query-api.md

# Query API Contract

## Query Syntax

### Basic Query Structure
```
```notex-query
FROM <property_filters>
[WHERE <conditions>]
[ORDER BY <property> [ASC|DESC]]
[GROUP BY <property>]
[LIMIT <number>]
```
```

### Property Filters
```yaml
# Filter by property existence
status:          # Returns documents with 'status' property

# Filter by property value
status: "draft"  # Returns documents where status = "draft"

# Multiple property filters
status: "draft"
priority: "high"
tags: ["research", "urgent"]
```

### Conditions
```yaml
# Comparison operators
WHERE priority > 5
WHERE created_at >= "2024-01-01"
WHERE status != "archived"

# Logical operators
WHERE status = "active" AND priority > 3
WHERE status = "urgent" OR priority > 5
WHERE NOT status = "archived"

# String matching
WHERE title CONTAINS "important"
WHERE tags STARTS_WITH "project"
WHERE author ENDS_WITH "@company.com"

# Array operations
WHERE tags INCLUDES "urgent"
WHERE tags SIZE > 3

# Date operations
WHERE created_at BEFORE "2024-06-01"
WHERE updated_at AFTER "2024-01-01"
WHERE due_date WITHIN 7d
```

## Query Execution API

### Parse Query
**Input**: Raw query string
**Output**: Parsed query object
```lua
{
  filters = {
    status = "draft",
    priority = "high"
  },
  conditions = {
    type = "AND",
    clauses = {
      { type = "comparison", field = "priority", operator = ">", value = 3 }
    }
  },
  order_by = { field = "created_at", direction = "DESC" },
  group_by = "status",
  limit = 50
}
```

### Execute Query
**Input**: Parsed query object
**Output**: Query results
```lua
{
  documents = {
    {
      id = "doc123",
      file_path = "/path/to/document.md",
      properties = {
        status = "draft",
        priority = "high",
        created_at = "2024-03-15T10:30:00Z"
      }
    }
  },
  total_count = 1,
  execution_time_ms = 45,
  query_hash = "abc123def"
}
```

## Virtual Buffer API

### Create Query View
**Input**: Query results
**Output**: Virtual buffer configuration
```lua
{
  buffer_id = 5,
  window_id = 1002,
  lines = {
    "Results for: status=draft, priority=high",
    "",
    "| Title        | Status | Priority | Created     |",
    "|--------------|--------|----------|-------------|",
    "| Research Doc | draft  | high     | 2024-03-15  |"
  },
  mappings = {
    ["<CR>"] = "open_document",
    ["e"] = "edit_document",
    ["q"] = "close_query_view"
  },
  syntax = "notex_query_results"
}
```

### Update Document Property
**Input**: Document ID, property name, new value
**Output**: Update result
```lua
{
  success = true,
  document_id = "doc123",
  property = "status",
  old_value = "draft",
  new_value = "review",
  updated_file = true
}
```

## Error Handling

### Query Parse Errors
```lua
{
  error_type = "parse_error",
  message = "Invalid syntax at line 3: column 5",
  line = 3,
  column = 5,
  context = "WHERE priority >"
}
```

### Query Execution Errors
```lua
{
  error_type = "execution_error",
  message = "Property 'nonexistent' not found in any document",
  property_name = "nonexistent",
  suggested_properties = {"status", "priority", "type"}
}
```

### Document Update Errors
```lua
{
  error_type = "update_error",
  message = "File not found or not writable",
  document_id = "doc123",
  file_path = "/path/to/missing.md"
}
```