konecty/konecty-find

Konecty Find

Search and query records in any Konecty module.

Prerequisites

Requires credentials from konecty-session: KONECTY_URL and KONECTY_TOKEN in ~/.konecty/.env. If not present or expired, ask the user to run konecty-session first.

If the module name or field names are unknown, use konecty-modules to discover them.

APIs

| Endpoint | Method | Description | |----------|--------|-------------| | /rest/data/:document/find | GET / POST | Simple document search | | /rest/query/json | POST | Cross-module query with relations and aggregators | | /rest/query/sql | POST | SQL query (translated to JSON query internally) |

Script

python3 scripts/find.py find <Document> [options]    # simple find
python3 scripts/find.py query <Document> [options]   # cross-module JSON query
python3 scripts/find.py sql "<SQL>" [options]         # SQL query

All subcommands accept --host and --token to override credentials, and --output json|ndjson.

find options

| Option | Description | |--------|-------------| | --filter '<JSON>' | KonFilter as JSON string | | --fields 'f1,f2' | Comma-separated field names to return | | --sort 'field:asc' | Sort shorthand or JSON array | | --limit N | Max records (default: 50, -1 for no limit) | | --start N | Offset/skip for pagination (default: 0) | | --post | Force POST even without filter |

query options

Same as find, plus:

| Option | Description | |--------|-------------| | --relations '<JSON>' | Relations array as JSON string | | --include-meta | Request _meta line as first NDJSON record | | --no-total | Skip total count calculation (faster) |

---

Quick Examples

Simple filter by field value

python3 scripts/find.py find Contact \
  --filter '{"match":"and","conditions":[{"term":"status","operator":"equals","value":"active"}]}' \
  --fields "code,name,status" --limit 20

Full-text search

python3 scripts/find.py find Contact \
  --filter '{"match":"and","textSearch":"John Doe"}' \
  --fields "code,name,email"

Date range with dynamic variable

python3 scripts/find.py find Opportunity \
  --filter '{"match":"and","conditions":[{"term":"createdAt","operator":"between","value":{"greater_or_equals":"$monthsAgo:3","less_or_equals":"$now"}}]}'

Lookup field filter

python3 scripts/find.py find Opportunity \
  --filter '{"match":"and","conditions":[{"term":"contact._id","operator":"equals","value":"<contactId>"}]}'

Cross-module query with relation aggregation

python3 scripts/find.py query Contact \
  --fields "code,name" \
  --relations '[{"document":"Opportunity","lookup":"contact","aggregators":{"count":{"aggregator":"count"},"totalValue":{"aggregator":"sum","field":"value.value"}}}]' \
  --limit 100

SQL query

python3 scripts/find.py sql \
  "SELECT ct.code, ct.name, COUNT(o._id) AS deals FROM Contact ct INNER JOIN Opportunity o ON ct._id = o.contact._id GROUP BY ct.code, ct.name ORDER BY deals DESC LIMIT 50"

Pagination

# Page 1
python3 scripts/find.py find Contact --limit 50 --start 0
# Page 2
python3 scripts/find.py find Contact --limit 50 --start 50

---

Filter Structure

{
  "match": "and",
  "conditions": [
    { "term": "status", "operator": "equals", "value": "active" }
  ],
  "textSearch": "optional full-text string",
  "filters": [
    { "match": "or", "conditions": [...] }
  ]
}

• match: "and" | "or" — how to combine conditions
• conditions: array of { term, operator, value } objects
• textSearch: full-text search across indexed text fields
• filters: nested sub-groups for complex AND/OR combinations
• A condition with "disabled": true is ignored at runtime

Common operators

| Operator | Use for | |----------|---------| | equals / not_equals | Exact match | | contains / not_contains | Substring (case-insensitive) | | starts_with / end_with | Prefix / suffix | | in / not_in | Match/exclude a list — value must be an array | | greater_than / less_than | Numeric/date comparison | | greater_or_equals / less_or_equals | Inclusive numeric/date comparison | | between | Inclusive range — value: { "greater_or_equals": ..., "less_or_equals": ... } | | exists | Field presence — value: true or false |

For the full operator list, field-type matrix, dot-notation for sub-fields, and dynamic date variables ($now, $monthsAgo:N, $user, etc.), see references/filter-operators.md.

---

Response Format

/rest/data/:document/find returns JSON:

{ "success": true, "total": 120, "data": [...] }

/rest/query/json and /rest/query/sql return NDJSON (application/x-ndjson), one object per line. With includeMeta: true, the first line is { "_meta": { "success": true, "total": N } }.

The script prints # Total: N Returned: N to stderr and the data to stdout, making it easy to pipe: python3 scripts/find.py find Contact | jq ..

---

Further Reference

• references/filter-operators.md — Complete operator list, operators by field type, sub-field paths, dynamic values, nested filter examples
• references/cross-module-query.md — Full query/json schema, relations, aggregators, groupBy, SQL interface