Redis SQL Trino

Use rediss:// to enable TLS; certificate properties alone do not change a redis:// connection into a TLS connection. Set the ACL username and password with redisearch.username and redisearch.password, or use the authentication portion of a Redis URI. When a separate password is set, it overrides URI credentials; a separate username is applied with that password. Avoid putting passwords in shell history or committed configuration files. For deployments using Trino’s secrets support, see Trino secrets management.

A TLS connection with separate credentials can look like this:

The environment variable must exist in every Trino node’s process. Omit cacert-path when the default trust configuration already trusts the server certificate. For mutual TLS, also configure redisearch.cert-path and redisearch.key-path, and redisearch.key-password when the private key is encrypted. Certificate paths refer to files inside the Trino runtime; mount them into containers on every node. redisearch.insecure=true disables peer verification and should be limited to controlled diagnostics.

Set redisearch.cluster=true only when the database exposes the OSS Cluster API. A sharded Redis Software or Cloud database behind a single database endpoint can still use cluster=false; sharding alone does not imply cluster routing. Check the database’s connection mode and advertised node addresses rather than deriving this setting from its shard count.

An ACL must allow the index commands and access to the covered document keys. Discovery reads FT._LIST, FT.INFO, FT.SEARCH and GET __trino:columns:<index>; scans use FT.AGGREGATE, FT.CURSOR and, when needed, exact hash reads. Writes additionally need the hash/delete commands for their statements, and DDL needs FT.CREATE, FT.ALTER or FT.DROPINDEX plus access to the type metadata keys. Scope permissions to the indexes, document prefixes and operations the deployment uses, and test with the actual service account. Allowing PING alone is insufficient.

Do not carry redisearch.default-limit or redisearch.table-cache-expiration into a new catalog. Both are declared defunct and rejected at startup. The former silently capped scans; use a SQL LIMIT for an intentional result limit. Use redisearch.table-cache-refresh for metadata refresh.

Run these commands with a Redis CLI connected to your database, using an unused key prefix and index name:

Wait until FT.INFO reports indexing as 0, then query from the Trino CLI:

abv reads as DOUBLE; id and name read as VARCHAR. NUMERIC filters can run in Redis. A TEXT field’s SQL equality is exact string equality, not a request for arbitrary full-text matching; see filter semantics.

Create a JSON document and an index with explicit field aliases:

After background indexing finishes:

The SQL columns use the aliases sku, name and price, rather than the JSON paths. The "$" column contains the full document as JSON text. Indexing a JSON array does not turn its elements into separate SQL rows; a row represents a document. Use Trino JSON functions to interpret document text when necessary. The connector does not insert or update JSON documents; DELETE and the delete branch of MERGE can remove them.

An index’s indexed fields define its primary set of SQL columns. The connector also samples the first 10 documents for unindexed fields; those columns are VARCHAR and are not a complete union of every document’s fields. Use explicit indexed fields when a stable SQL schema matters.

Metadata refresh is separate from row freshness. redisearch.table-cache-refresh refreshes index descriptions and saved types, not a cached copy of query results. Each query reads Redis; changes to existing fields do not require a schema version or a metadata refresh. A newly added field can remain absent from the cached schema until the background refresh completes.

To remove only an example index while retaining its data, use FT.DROPINDEX guide_beers in Redis without DD. SQL DROP TABLE uses DD and deletes the documents too.

Each Redis Query Engine index is a table in the default schema (see redisearch.default-schema-name). A table has these columns:

Columns created with CREATE TABLE or ALTER TABLE ... ADD COLUMN read back as the types they were created with instead; see column types.

After FT.CREATE over existing keys, or ALTER TABLE ... ADD COLUMN (which runs FT.ALTER), Redis indexes the documents in the background. Until it finishes, queries on that index fail with REDISEARCH_INDEX_NOT_READY (Index beers is still being built (42% indexed) ...) instead of returning incomplete results. Retry once FT.INFO reports indexing as 0. CREATE TABLE creates its index with SKIPINITIALSCAN, so a new table can be queried right away.

The catalog exposes one configured schema. redisearch.default-schema-name changes its name; it does not create or select a Redis database or key prefix. Use fully qualified catalog.schema.table names when a client has no default catalog/schema.

These statements fail with a This connector does not support ... error:

Writes also fail when fault-tolerant execution is enabled (retry-policy other than NONE).

Use a dedicated key prefix for tables whose lifecycle Trino manages. A new table named guide_orders uses the index guide_orders, document prefix guide_orders: and type metadata key __trino:columns:guide_orders.

ALTER TABLE …​ ADD COLUMN changes the index and saved type metadata, but does not populate the new field in existing hashes. Missing values read as SQL NULL. Adding an indexed field can trigger background reindexing; wait for it to finish before reading the table.

INSERT sends one pipelined HSET per row, using a generated ULID key under the index’s first prefix. A prefix without a trailing : has one appended; if no usable prefix is found, the writer uses <table>:. An INSERT into an externally created index therefore requires a compatible key prefix for its rows to be indexed. NULL values and omitted columns are not written. SQL columns do not declare Redis keys or enforce primary-key uniqueness. Two INSERTs with the same order_id create two hashes. UPDATE and MERGE match SQL predicates; they do not turn an ordinary ID column into a uniqueness constraint.

Writes are not transactional across rows. A failed INSERT, UPDATE, DELETE or MERGE can leave completed Redis changes in place; retrying a write may add duplicates or repeat changes. Inspect the affected rows and application keys before retrying. Do not assume Trino rollback reverses all document writes.

CREATE TABLE AS SELECT creates a HASH index and writes the selected rows using the same rules:

Use DROP TABLE guide_orders_copy and DROP TABLE guide_orders only when you intend to delete their data. For externally owned indexes, removing an index without its documents must be done in Redis with FT.DROPINDEX without DD.

Other types, such as ARRAY, MAP, ROW, VARBINARY and TIME, fail with Unsupported column type.

Redis keeps only each field’s index type, which columns of several Trino types share. So CREATE TABLE, CREATE TABLE AS SELECT and ALTER TABLE ... ADD COLUMN also save the columns' Trino types, as JSON in the string key __trino:columns:<table>, such as {"regionkey":"bigint","name":"varchar(25)"}, and DROP TABLE deletes the key. Columns read back as those types in DESCRIBE, SHOW CREATE TABLE, information_schema and queries, and INSERT takes values of those types. CREATE TABLE AS SELECT keeps bounded types, so SELECT 'a' AS id makes a varchar(1) column.

The types in the key don’t apply to:

Redis returns a NUMERIC field loaded by name formatted as a double, rounded to 12 significant digits unless it’s an integer. DOUBLE and DECIMAL scans use LOAD * on HASH tables to retain exact stored values. BIGINT and TIMESTAMP(3) scans load named fields and recover possibly rounded large values with exact HGETs. JSON scans use DIALECT 3 to read numbers as stored. NUMERIC fields still hold doubles for queries and aggregations in Redis: see Pushdown.

A value its column’s type can’t hold, such as 4.5 written by another client to a BIGINT column, fails the query with Value '4.5' is not a valid bigint. To read the table with the default types instead, delete the key (DEL __trino:columns:<table>); the first query after redisearch.table-cache-refresh seconds has the connector describe the table again, and the queries after it use the default types.

TAG fields created by the connector aren’t full-text TEXT fields. They’re CASESENSITIVE and split values into tags on the ASCII unit separator (\x1f) instead of ,, so Redis can prefilter = and IN on values containing commas, and doesn’t return rows that only differ in case.

For a read, the coordinator resolves the index schema and saved Trino column types, then chooses operations that can be evaluated in Redis. Each worker source verifies that its index has finished background indexing and starts an FT.AGGREGATE request. Document scans load projected values; grouped queries use GROUPBY and REDUCE. FT.CURSOR READ fetches additional batches until the cursor is exhausted. The connector prefetches one cursor batch while Trino processes the previous batch, and attempts to delete a live cursor when a source closes.

Large eligible document scans can create several sources through parallel scan planning. Pushed-down limits, ordering and aggregations remain single-source operations. Trino applies remaining filters, joins, sorting and expressions to the returned rows. A query that cannot reduce rows in Redis can read every document in the index, even if its final result is small.

Redis evaluates these parts of a query. Trino evaluates everything else on the rows Redis returns.

redisearch.query-timeout-ms sets the per-query Redis aggregation timeout in milliseconds; 0 uses the server default. For example, redisearch.query-timeout-ms=30000 requests 30 seconds. Trino query limits, Redis server policy and client connection/command timeouts remain separate constraints; a larger aggregation timeout does not remove them. Where the deployment permits it, configure Redis’s timeout policy to fail instead of returning partial results, following Redis Query Engine configuration. The connector rejects aggregation replies containing server warnings with REDISEARCH_INCOMPLETE_RESULT.

A lost cursor-read reply fails with REDISEARCH_CURSOR_REPLY_LOST rather than replaying the read: Redis may already have consumed its batch. Restore server/network health and rerun the complete query. The connector can reconnect for later queries and performs bounded retries for idempotent cursor deletion, but does not resume a failed result stream. A client that has received rows before a later scan error must treat the query as failed and discard those rows.

Redis cursors and the connector’s follow-up exact hash reads do not provide snapshot isolation. Concurrent updates or deletes can change the values observed during a scan. Parallel scans additionally require a stable partition field to avoid moving documents between ranges while they are read. For repeatable analytical checks, use a quiescent dataset or an isolated copy and compare complete query results.

Start with the defaults: aggregation pushdown enabled, automatic splits, eight scan connections per node and 1,000 rows per cursor batch. A selective query or supported aggregation usually benefits most from returning fewer rows from Redis. A full scan can instead be limited by network transfer, exact-value reads or conversion into Trino pages. Use EXPLAIN to see the chosen filters, limits, sort keys and aggregates, then EXPLAIN ANALYZE on a representative read to measure its execution. EXPLAIN ANALYZE executes the query.

Connector source metrics include redis.aggregate.requests, redis.cursor.requests, redis.rows.received, redis.exact-hash-reads, redis.request-wall-time and redis.row-conversion-time. Inspect these alongside Redis CPU, query latency and Trino worker activity. Request wall time includes waiting and network time; it is not a measurement of Redis CPU time.

For unbounded scans of at most two requested columns, redisearch.narrow-scan-cursor-count can reduce cursor round trips. Larger batches retain more rows in memory; test them with concurrent queries before adopting them. Selecting only needed columns also reduces work, although exact DOUBLE and DECIMAL HASH reads can require LOAD *.

A pushed-down global aggregate must process all matching documents before returning its result. WITHCURSOR COUNT batches the output, not the global computation. More client connections or smaller batches do not by themselves remove server-side contention. Evaluate Redis query performance factor independently of connector scan splits. Additional query workers consume CPU and can increase overhead; measure the target workload.

When large aggregates interfere with latency-sensitive traffic, compare this catalog setting:

Trino then computes aggregates from document batches while supported filters still run in Redis. This transfers more rows and can make analytical queries slower. Use Trino resource groups to bound analytical concurrency, and measure application tail latency as well as SQL throughput.

The repository retains timings and reproduction instructions rather than promising a workload-independent speedup. The README distinguishes historical CI timings, pre-v0.4.0 comparisons and newer full-data experiments. Treat each result as evidence for its pinned build, dataset, server configuration and concurrency.

The connector uses Lettuce for Redis communication. Lettuce supports multiple CPU cores through Netty I/O event loops and computation thread pools. Its default pool sizes follow the available CPU count, with a minimum of two threads, unless configured otherwise. See Lettuce client resources for the threading settings. A physical connection processes its network events on one event loop; additional client threads do not automatically partition a query or create more Trino sources.

The connector’s existing connection pool supports concurrency between scans. Multiple splits let a single document scan use several connections and Trino source pipelines. Tune Redis query workers independently and measure the combined configuration; client-side parallelism alone does not determine server-side query concurrency.

Automatic split selection is the default (redisearch.scan-splits=0). The planner targets at least 250,000 matching rows per split and selects the largest count allowed by the estimated CPU capacity (active Trino workers times coordinator CPU count), the connection pool (eight by default), and a hard ceiling of 64. Small tables and selective filters use one split. A filter’s match count is checked before choosing parallelism. For HASH indexes without explicit boundaries, the planner examines up to three indexed NUMERIC fields, obtains their MIN/MAX in one bounded statistics query, and checks the counts of the proposed ranges. A field is rejected if one partition would contain at least 80% of the matching documents; the planner then tries another candidate.

Discovery results, including unsupported cases, are cached for five minutes (up to 256 entries). Statistics queries have a ten-second server timeout and count probes have a one-second timeout; unavailable or partial statistics fall back to one split. The first scan can therefore pay a discovery cost; subsequent scans can reuse discovery results. Selective-filter count probes still run before the discovery cache is consulted, so a cached plan does not eliminate all planning requests.

MIN/MAX discovery is a server-side aggregate and can delay concurrent point traffic when Redis query workers are disabled; configured boundaries avoid this discovery work. This is a cost heuristic, not a guarantee of the optimal count under every load. Use the benchmark and explicit overrides when tuning a shared deployment. JSON arrays support explicit partition fields and cut points; automatic MIN/MAX discovery currently applies to HASH indexes.

Set redisearch.scan-splits=1 to force one source. To override automatic selection and supply known boundaries:

This partitions one document scan into four Trino sources with independent cursors and distinct scan connection slots on each worker. The NUMERIC field must already be indexed; the connector does not alter the index. Explicit boundaries skip discovery. Choose cut points from the field’s distribution; uneven partitions still return complete results but can limit the speedup. If fewer splits are allowed, the connector selects evenly spaced cut points from the configured list and merges the other intervals.

The lowest partition includes values below the first cut and documents without an indexed value; the highest includes every value above the last cut. For multi-valued JSON, partitions use differences of nested range matches, so documents matching multiple ranges appear once. All partitions preserve static and dynamic filters. Each source rechecks its index schema before querying and fails if the partition field has become unsafe.

Pushed-down LIMIT, ORDER BY/top-N, grouping and reducers always use one split. Trino can still compute joins, unsupported expressions and exact DISTINCT from the parallel document sources. The normal cursor timeout, failure, exact BIGINT recovery and best-effort deletion behavior applies to each source.

The pool bounds connections per worker; the split bound applies per query, not to the number of simultaneous queries. Configure Trino resource groups to bound overall analytical concurrency when sharing Redis with latency-sensitive traffic. Parallel scans do not provide snapshot isolation: keep the partition field stable during a scan, as moving a document across cut points during execution can cause omissions or repetitions.

The Trino JDBC driver allows users to access Trino from Java-based applications, and other non-Java applications running in a JVM.

Refer to the Trino documentation for setup instructions.

The following is an example of a JDBC URL used to create a connection to Redis SQL Trino:

The connection targets Trino, which then connects to Redis. The path selects the catalog and schema; change redisearch if you used another catalog filename. Use a JDBC driver matching the Trino server version for this deployment. For a secured Trino endpoint, configure the driver’s TLS and authentication options separately from the Redis catalog’s credentials.

Configure a supported Trino/Presto connection to the Trino coordinator host and port, then choose the Redis catalog and its configured schema. Redis’s database port is not a JDBC endpoint. Refer to the Tableau connection instructions for the driver’s installation and connection fields. For Apache Superset or another SQL client, use its Trino integration and the same catalog/schema. Validate an ordinary SELECT in the Trino CLI first so that driver setup can be diagnosed separately from connector or Redis errors.

Use the CLI bundled with the stock container, or download the executable CLI JAR for Trino 483. For a locally installed CLI:

The last two statements require the example index or an equivalent table of your own. See the Trino CLI reference for TLS, authentication and output options.

Trino requires a 64-bit version of Java 25. Use Eclipse Temurin Java 25, at least 25.0.1, consistent with Trino and the project build. Confirm that JAVA_HOME and java point to that JDK; Java 26 is not a supported substitute. See Trino deployment requirements.

Download the Trino server tarball and unpack it.

Trino needs a data directory for storing logs, etc. It is recommended to create a data directory outside of the installation directory, which allows it to be easily preserved when upgrading Trino.

Create an etc directory inside the installation directory to hold configuration files.

Create a node.properties file.

Create a JVM config file. The following uses a 4 GiB heap for a small trial; the host needs additional memory for native allocations, the operating system and other services. Size production heaps using Trino’s deployment guidance.

Create a config properties file. This node acts as both coordinator and worker. The example HTTP endpoint has no authentication; use it only on a trusted local network and configure Trino security before exposing it to other users.

Create a logging configuration file.

Download latest release and unzip without any directory structure under plugin/redisearch:

Create a etc/catalog subdirectory:

Create a RediSearch connector configuration file:

Change and/or add properties as needed.

Start the Trino server:

Download and run the CLI as the current user:

List tables and run a SQL query: