Faz Docs

Connect faz to an OpenSearch cluster. Query DSL queries, basic_auth, schema discovery with vector-field type recognition.

OpenSearch is the AWS-led fork of Elasticsearch. faz's connector is nearly identical to the Elasticsearch connector; the only practical difference is the default port faz's docker-compose uses (to coexist with Elasticsearch on a developer machine) and explicit recognition of knn_vector mapping types.

Default port	Query language	Write support	Schema discovery	Driver
9200	Query DSL (JSON)	Yes (RBAC-gated)	`_mapping` API	`opensearch-py`

Quick example

faz.yaml

databases:
  - name: <database>          # used as --database <database> in queries
    type: opensearch
    host: localhost
    port: 9200
    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 and index DDL)

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

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

Field	Type	Default	Notes
`host`	string	`localhost`	OpenSearch host.
`port`	integer	`9200`	HTTP API port. faz's bundled docker-compose maps to 9201 to coexist with Elasticsearch.
`database`	string	`""`	Usually empty.
`username`	string	`""`	Username for basic auth.
`password`	string	`""`	Password.
`ssl`	boolean	`false`	When `true`, uses HTTPS.
`extra`	mapping	`{}`	Reserved.

Capabilities

Functionally identical to Elasticsearch:

Query DSL bodies for _search / _count directly.
Other paths via {"method": ..., "path": ..., "body": ...} envelope.
Schema discovery via _mapping.
Type mapping covers OpenSearch's knn_vector field type alongside Elasticsearch's dense_vector.

User-index filtering excludes .-prefixed indices and kibana, security, fleet, apm, metrics-, logs-, traces- patterns.

Limitations

Same as Elasticsearch:

script / scripted_field / script_fields / runtime_mappings are blocked by the Injection Analyser.
System indices are excluded from schema discovery.
No streaming for large result sets.

Troubleshooting

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

AuthenticationException — credentials are wrong, or the security plugin requires a different auth method (mutual TLS, IAM signed for AWS-managed OpenSearch).

AWS-managed OpenSearch — basic auth works only when fine-grained access control is enabled. Otherwise the cluster expects IAM-signed requests, which the OpenSearch Python client doesn't do by default. Front faz with a sidecar that does IAM signing, or use AWS's open-source distribution outside their managed service.

For the broader troubleshooting flow, see Connection failed.

Elasticsearch — sibling connector with the same query shape.
Databases overview — cross-connector basics.
faz.yaml — the full config schema.

OpenSearch

Quick example

Configuration

Capabilities

Limitations

Troubleshooting

Related

On this page