Elasticsearch

faz's Elasticsearch connector speaks the standard Query DSL. Reads use _search and _count directly; writes and admin operations use a JSON envelope with method and path fields.

Quick example

databases:
  - name: <database>          # used as --database <database> in queries
    type: elasticsearch
    host: localhost
    port: 9200
    database: ""              # left empty; index name is part of the query
    username: <username>
    password: <password>
    ssl: false

permissions:
  - database: <database>      # must match `name:` above
    access: R
    # access codes:
    # R    read only           — _search, _count
    # W    write only          — _doc, _update, _delete_by_query (no reads)
    # RW   read + write
    # RA   read + append       — reads + _doc creates
    # RWA  read + write, no DELETE
    # A    admin (incl. mapping mutations, _template, index DDL)

See Permissions for the full model, per-table overrides, and the operation matrix.

Read against an index:

faz query '{"query":{"match_all":{}},"size":5}' --database <database> --table <index> --language es_dsl

uv run faz query '{"query":{"match_all":{}},"size":5}' --database <database> --table <index> --language es_dsl

python -m faz query '{"query":{"match_all":{}},"size":5}' --database <database> --table <index> --language es_dsl

Configuration

Capabilities

The query body shape depends on the operation:

• _search / _count — pass the standard Query DSL body directly. Example: {"query": {"match_all": {}}, "size": 10}.
• Other paths — wrap with {"method": "GET|POST|PUT|DELETE", "path": "/idx/_path", "body": {...}}.

Schema discovery walks the _mapping API, returning fields with their types. Vector-style fields (knn_vector, dense_vector) are flagged as such in the discovered metadata.

User-index filtering: schema discovery excludes indices whose names start with any of ., kibana, security, fleet, apm, metrics-, logs-, traces-. This prevents cluster-internal indices from cluttering the agent's view of the data.

Limitations

• script / scripted_field / script_fields / runtime_mappings are blocked by the Injection Analyser. Painless and other scripted queries can execute arbitrary code.
• The connector blocks non-GET methods at _search. Write operations need to go through their own paths (_doc, _update, _bulk, etc.).
• No streaming — large _search responses are buffered. Use size and pagination via from/search_after.
• System indices are hidden by default. If you want to expose .kibana or another dot-prefixed index, you'll need to query it explicitly by name; schema discovery still won't include it.

Troubleshooting

ConnectionError — Elasticsearch isn't listening on host:port. Test with curl http://host:port/_cluster/health.

AuthenticationException / 401 — credentials are wrong, or the cluster expects API keys instead of basic auth. faz currently uses HTTP basic; for API-key auth, you'll need to set up a basic-auth-aware proxy in front.

SSL: CERTIFICATE_VERIFY_FAILED — your cluster uses a self-signed cert. Either provide the CA bundle (not yet exposed in faz.yaml) or relax cert verification at the network layer.

Empty schema — the user lacks view_index_metadata or monitor cluster privilege. Grant the role.

For the broader troubleshooting flow, see Connection failed.

Related

• Databases overview — cross-connector basics.
• OpenSearch — sibling search engine, very similar shape.
• faz.yaml — the full config schema.