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

# 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

{
  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

{
  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

{
  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

{
  success = true,
  document_id = "doc123",
  property = "status",
  old_value = "draft",
  new_value = "review",
  updated_file = true
}

Error Handling

Query Parse Errors

{
  error_type = "parse_error",
  message = "Invalid syntax at line 3: column 5",
  line = 3,
  column = 5,
  context = "WHERE priority >"
}

Query Execution Errors

{
  error_type = "execution_error",
  message = "Property 'nonexistent' not found in any document",
  property_name = "nonexistent",
  suggested_properties = {"status", "priority", "type"}
}

Document Update Errors

{
  error_type = "update_error",
  message = "File not found or not writable",
  document_id = "doc123",
  file_path = "/path/to/missing.md"
}

3.2 KiB Raw Permalink Blame History