172 lines
3.2 KiB
Markdown
172 lines
3.2 KiB
Markdown
|
# 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"
|
||
|
}
|
||
|
```
|