Skip to content

Commit 38b03ef

Browse files
bankerbanker
committed
Revise README
1 parent e1047f7 commit 38b03ef

File tree

1 file changed

+87
-7
lines changed

1 file changed

+87
-7
lines changed

‎README.adoc‎

Lines changed: 87 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -11,21 +11,101 @@
1111
image:{project-url}/actions/workflows/early-access.yml/badge.svg["Build Status", link="{project-url}/actions/workflows/early-access.yml"]
1212
image:https://codecov.io/gh/{project-owner}/{project-name}/branch/master/graph/badge.svg?token={codecov-token}["Coverage", link="https://codecov.io/gh/{project-owner}/{project-name}"]
1313

14-
Redis SQL is a https://trino.io[Trino] connector which allows access to RediSearch data from Trino.
14+
Redis SQL is a https://trino.io[Trino] connector for https://redis.io/docs/stack/[Redis Stack], https://redis.com/redis-enterprise-cloud/overview/[Redis Cloud], and https://redis.com/redis-enterprise-software/overview/[Redis Enterprise].
1515

16-
NOTE: RediSearch 2.0 or later is required.
16+
Trino is a distributed SQL engine designed to efficiently query large amounts of data for data warehousing and analytics (OLAP) applications. The Redis SQL Trino connector that lets you use Trino to query your Redis data using SQL. This implementation takes advantage of the indexing and querying capabilites of Redis Stack. As such, this connector generally outperforms the https://trino.io/docs/current/connector/redis.html[standard Redis Trino connector], which cannot take advantage of these indexed queries.
17+
18+
19+
== Table of Contents
20+
21+
:toc:
22+
23+
== Background
24+
25+
Redis is an in-memory data store designed to serve data with the fastest possible response times. For this reason, Redis is frequently used for caching OLTP-style application queries. Redis Stack is an extension to Redis that, among other things, lets you index your data and then efficiently query it using a custom query language. We built the Redis SQL Trino connector so that you can query Redis using any number of BI tools. For example, you can use this connector with Trino to query and visualize your Redis data in Tableau.
26+
27+
== Quick start
28+
29+
To understand how Redis SQL works, it's best to try it for yourself. View the screen recording or follow the steps below:
30+
31+
image::https://asciinema.org/a/526185.svg[asciicast,link=https://asciinema.org/a/526185]
32+
33+
First, clone this git repository:
34+
[source,console,subs="verbatim,attributes"]
35+
----
36+
git clone {project-url}.git
37+
cd {project-name}
38+
----
39+
40+
Next, use Docker Compose to launch containers for Trino and Redis Stack:
41+
[source,console]
42+
----
43+
docker-compose up
44+
----
45+
46+
This example uses a small data set describing a collection of beers. To load the data set, you'll need to have https://developer.redis.com/riot/riot-file/index.html[riot-file] installed locally (see the https://developer.redis.com/riot/riot-file/index.html[riot-file] installation instructions.
47+
48+
Next, use `riot-file` to import the sample data set into Redis:
49+
[source,console]
50+
----
51+
riot-file -h localhost import https://storage.googleapis.com/jrx/beers.json hset --keyspace beer --keys id
52+
----
53+
54+
Each beer is represented as a Redis hash. Start the Redis CLI to examine this data. For example, here's how you can view the "Beer Town Brown" record:
55+
[source,console]
56+
----
57+
docker exec -it redis /opt/redis-stack/bin/redis-cli
58+
127.0.0.1:6379> hgetall beer:190
59+
----
60+
61+
Next, create an index on the beer data. While still in the Redis CLI, you can create the required index by running the following `FT.CREATE` command:
62+
[source,console]
63+
----
64+
127.0.0.1:6379> FT.CREATE beers ON HASH PREFIX 1 beer: SCHEMA id TAG SORTABLE brewery_id TAG SORTABLE name TEXT SORTABLE abv NUMERIC SORTABLE descript TEXT style_name TAG SORTABLE cat_name TAG SORTABLE
65+
----
66+
67+
Now that you've indexed the data set, you can query it using SQL statements through Trino. Start the Trino CLI:
68+
[source,console]
69+
----
70+
docker exec -it trino trino --catalog redisearch --schema default
71+
----
72+
73+
View "Beer Town Brown" using SQL:
74+
[source,console]
75+
----
76+
trino:default> select * from beers where id = '190';
77+
----
78+
79+
Show all beers with an ABV greater than 3.2%:
80+
[source,console]
81+
----
82+
trino:default> select * from beers where abv > 3.2 order by abv desc;
83+
----
84+
85+
== Installation
86+
87+
To use Redis SQL Trino, you'll need a working Trino installation. See the https://trino.io/docs/current/installation.html[Trino installation and deplyoment guide] for details.
1788

18-
== Documentation
89+
Next, you'll need to install the Redis SQL Trino plugin and configure it. See https://redis-field-engineering.github.io/redis-sql/#redisearch-connector[plugin installation] and https://redis-field-engineering.github.io/redis-sql/#configuration[plugin configuration].
1990

20-
Documentation is available at link:{documentation-url}[{documentation-url}].
91+
== Usage
92+
93+
The example above uses the https://trino.io/docs/current/client/cli.html[Trino CLI] to access your data. Most real world applications will use the https://trino.io/docs/current/client/jdbc.html[Trino JDBC driver] to issue queries. See the https://redis-field-engineering.github.io/redis-sql/#clients[Redis SQL Trino] documentation for details.
2194

2295
== Support
2396

24-
Contact us on the https://forum.redis.com/[Redis Forum] or create an issue on {project-url}/issues[Github] where we provide support on a good faith effort basis.
97+
Redis SQL Trino is supported by the Redis Field Engineering team in the good faith effort basis. To report bugs, request features, or receive assistance, please {project-url}/issues[file an issue].
98+
99+
== License
100+
101+
Redis SQL is licensed under the MIT License. Copyright (c) 2023, Redis, Inc.
102+
103+
NOTE: RediSearch 2.0 or later is required.
104+
105+
Complete documentation is available at link:{documentation-url}[{documentation-url}].
25106

26107
== Docker Example
27108

28-
image::https://asciinema.org/a/526185.svg[asciicast,link=https://asciinema.org/a/526185]
29109

30110
.Clone the project
31111
[source,console,subs="verbatim,attributes"]
@@ -43,7 +123,7 @@ docker-compose up
43123
.Create a RediSearch index
44124
[source,console]
45125
----
46-
docker exec redis /usr/local/bin/redis-cli FT.CREATE beers ON HASH PREFIX 1 beer: SCHEMA id TAG SORTABLE brewery_id TAG SORTABLE name TEXT SORTABLE abv NUMERIC SORTABLE descript TEXT style_name TAG SORTABLE cat_name TAG SORTABLE
126+
docker exec -it redis /opt/redis-stack/bin/redis-cli FT.CREATE beers ON HASH PREFIX 1 beer: SCHEMA id TAG SORTABLE brewery_id TAG SORTABLE name TEXT SORTABLE abv NUMERIC SORTABLE descript TEXT style_name TAG SORTABLE cat_name TAG SORTABLE
47127
----
48128

49129
.Add documents to the index

0 commit comments

Comments
 (0)