Redis 커넥터

Redis 커넥터는 Redis에 저장된 실시간 데이터를 조회할 수 있게 해줘요. Redis와 Hive 같은 서로 다른 시스템 사이의 데이터를 조인하는 데 쓸 수 있어요.

출처: 문서

본문

각 Redis 키/값 쌍은 Trino에서 단일 행으로 제시돼요. 테이블 정의 파일을 사용해 행을 셀(cell)로 분해할 수 있어요.

현재 Redis 키 중에는 string과 zset 타입만 지원하고, Redis 값 중에는 string과 hash 타입만 지원해요.

요구 사항 (Requirements)

카탈로그에서 커넥터를 사용해 Redis 데이터 소스에 연결하기 위한 요구 사항은 다음과 같아요.

Redis 5.0.14 이상 (Redis Cluster는 지원하지 않음)
Trino 코디네이터와 워커에서 Redis까지의 네트워크 접근. 기본 포트는 6379예요.

설정 (Configuration)

Redis 커넥터를 설정하려면 카탈로그 속성 파일 etc/catalog/example.properties를 만들고 속성을 적절히 교체하며 다음 내용을 넣어요.

connector.name=redis
redis.table-names=schema1.table1,schema1.table2
redis.nodes=host:port

여러 Redis 서버 (Multiple Redis servers)

필요한 만큼 많은 카탈로그를 가질 수 있어요. Redis 서버가 더 있으면 etc/catalog에 이름이 다른 속성 파일을 추가하고 .properties로 끝나게 하면 돼요.

설정 속성 (Configuration properties)

다음 설정 속성을 사용할 수 있어요.

속성 이름	설명
`redis.table-names`	카탈로그가 제공하는 모든 테이블 목록
`redis.default-schema`	테이블의 기본 스키마 이름
`redis.nodes`	Redis 서버 위치
`redis.scan-count`	키 스캔용 Redis 파라미터
`redis.max-keys-per-fetch`	MGET(key…) 같은 redis 명령에서 지정한 수의 키와 연관된 값 가져오기
`redis.key-prefix-schema-table`	Redis 키에 schema-name:table-name 접두사가 있음
`redis.key-delimiter`	`redis.key-prefix-schema-table`을 쓸 때 schema_name과 table_name을 구분하는 구분자
`redis.table-description-dir`	테이블 설명 파일이 있는 디렉터리
`redis.table-description-cache-ttl`	테이블 설명 파일의 캐시 시간
`redis.hide-internal-columns`	내부 컬럼이 테이블 스키마의 일부인지 제어
`redis.database-index`	Redis 데이터베이스 인덱스
`redis.user`	Redis 서버 사용자 이름
`redis.password`	Redis 서버 비밀번호
`redis.tls.enabled`	TLS 보안 활성화 여부
`redis.tls.keystore-path`	JKS 또는 PKCS12 키 스토어 파일 경로
`redis.tls.keystore-password`	키 스토어용 비밀번호
`redis.tls.truststore-path`	JKS 또는 PKCS12 트러스트 스토어 파일 경로
`redis.tls.truststore-password`	트러스트 스토어용 비밀번호

redis.table-names

이 카탈로그가 제공하는 모든 테이블을 쉼표로 구분한 목록. 테이블 이름은 한정되지 않을 수 있고(단순 이름) 기본 스키마(아래 참조)에 배치되거나, 스키마 이름으로 한정될 수 있습니다(.).

정의된 각 테이블에 대해 테이블 설명 파일(아래 참조)이 존재할 수 있어요. 테이블 설명 파일이 없으면 테이블은 내부 컬럼만 포함해요(아래 참조).

이 속성은 선택 사항이며, 커넥터는 redis.table-description-dir 속성에 지정된 테이블 설명 파일에 의존해요.

redis.default-schema

한정 스키마 이름 없이 정의된 모든 테이블을 담을 스키마를 정의해요.

이 속성은 선택 사항이며 기본값은 default예요.

redis.nodes

Redis 서버의 hostname:port 쌍.

이 속성은 필수이며 기본값이 없어요.

Redis Cluster는 지원하지 않아요.

redis.scan-count

커넥터가 SCAN을 사용해 데이터의 키를 찾을 때 Redis SCAN 명령의 내부 COUNT 파라미터. 이 파라미터는 Redis 커넥터의 성능을 조정하는 데 쓸 수 있어요.

이 속성은 선택 사항이며 기본값은 100이에요.

redis.max-keys-per-fetch

커넥터가 MGET 명령과 Pipeline HGETALL 명령을 사용해 키의 값을 찾을 때의 내부 키 수. 이 파라미터는 Redis 커넥터의 성능을 조정하는 데 쓸 수 있어요.

이 속성은 선택 사항이며 기본값은 100이에요.

redis.key-prefix-schema-table

true이면 테이블에 대해 schema-name:table-name 접두사가 있는 키만 스캔하고 다른 키는 모두 걸러 내요. false이면 모든 키를 스캔해요.

이 속성은 선택 사항이며 기본값은 false예요.

redis.key-delimiter

redis.key-prefix-schema-table이 true일 때 schema-name과 table-name을 구분하는 데 사용하는 문자.

이 속성은 선택 사항이며 기본값은 :이에요.

redis.table-description-dir

Trino 배포 안에서 테이블 설명 파일을 담는 하나 이상의 JSON 파일(반드시 .json으로 끝나야 함)이 있는 폴더를 참조해요.

테이블 설명 파일은 Trino 코디네이터 노드에서만 사용된다는 점에 유의하세요.

이 속성은 선택 사항이며 기본값은 etc/redis예요.

redis.table-description-cache-ttl

Redis 커넥터는 이 속성이 지정한 시간을 기다린 뒤 테이블 설명 파일을 동적으로 로드해요. 따라서 redis.table-description-dir 폴더에 .json으로 끝나는 파일을 추가·갱신·삭제할 때 redis.table-names 속성을 갱신하고 Trino 서비스를 재시작할 필요가 없어요.

이 속성은 선택 사항이며 기본값은 5m이에요.

redis.hide-internal-columns

테이블 설명 파일에 정의된 데이터 컬럼에 더해, 커넥터는 각 테이블에 여러 추가 컬럼을 유지해요. 이 컬럼들이 숨겨지면 쿼리에는 계속 사용할 수 있지만 DESCRIBE나 SELECT *에는 나타나지 않아요.

이 속성은 선택 사항이며 기본값은 true예요.

redis.database-index

조회할 Redis 데이터베이스.

이 속성은 선택 사항이며 기본값은 0이에요.

redis.user

Redis 서버의 사용자 이름.

이 속성은 선택 사항이며 기본값은 null이에요.

redis.password

비밀번호로 보호된 Redis 서버의 비밀번호.

이 속성은 선택 사항이며 기본값은 null이에요.

redis.tls.enabled

Redis 연결에 TLS를 활성화해요.

이 속성은 선택 사항이며 기본값은 false예요.

TLS가 활성화되면 커넥터는 redis.tls.truststore-path가 설정되지 않는 한 JVM 기본 트러스트 스토어를 사용해요.

redis.tls.keystore-path

클라이언트를 Redis 서버에 인증하는 데 사용하는 JKS 또는 PKCS12 키 스토어 파일 경로(mTLS에서만 필요).

이 속성은 선택 사항이며 기본값이 없어요.

redis.tls.keystore-password

redis.tls.keystore-path가 참조하는 키 스토어용 비밀번호.

이 속성은 선택 사항이며 기본값이 없어요.

redis.tls.truststore-path

Redis 서버의 TLS 인증서를 검증하는 데 사용하는 인증서(들)를 담은 JKS 또는 PKCS12 트러스트 스토어 파일 경로.

이 속성은 선택 사항이며 기본값이 없어요.

redis.tls.truststore-password

redis.tls.truststore-path가 참조하는 트러스트 스토어용 비밀번호.

이 속성은 선택 사항이며 기본값이 없어요.

내부 컬럼 (Internal columns)

정의된 각 테이블에 대해 커넥터는 다음 컬럼을 유지해요.

컬럼 이름	타입	설명
`_key`	VARCHAR	Redis 키.
`_value`	VARCHAR	키에 해당하는 Redis 값.
`_key_length`	BIGINT	키의 바이트 수.
`_value_length`	BIGINT	값의 바이트 수.
`_key_corrupt`	BOOLEAN	이 행의 키를 디코더가 디코딩하지 못했으면 true. true일 때 키에서 매핑된 데이터 컬럼은 잘못된 것으로 취급해야 함.
`_value_corrupt`	BOOLEAN	이 행의 메시지를 디코더가 디코딩하지 못했으면 true. true일 때 값에서 매핑된 데이터 컬럼은 잘못된 것으로 취급해야 함.

테이블 정의 파일이 없는 테이블에서는 _key_corrupt와 _value_corrupt 컬럼이 false예요.

테이블 정의 파일 (Table definition files)

Redis 커넥터를 사용하면 키/값 문자열이 특정 형식을 따르는 경우, Redis 키/값 쌍을 더 세분화된 셀로 축소할 수 있어요. 이 과정은 Trino에서 더 조회할 수 있는 새 컬럼을 정의해요.

테이블 정의 파일은 테이블에 대한 JSON 정의로 구성돼요. 파일 이름은 임의적일 수 있지만 .json으로 끝나야 해요.

{
    "tableName": ...,
    "schemaName": ...,
    "key": {
        "dataFormat": ...,
        "fields": [
            ...
        ]
    },
    "value": {
        "dataFormat": ...,
        "fields": [
            ...
       ]
    }
}

필드	필수	타입	설명
`tableName`	필수	string	이 파일이 정의하는 Trino 테이블 이름.
`schemaName`	선택	string	테이블을 담을 스키마. 생략하면 기본 스키마 이름 사용.
`key`	선택	JSON 객체	값을 키에 매핑한 데이터 컬럼의 필드 정의.
`value`	선택	JSON 객체	값 자체에 매핑한 데이터 컬럼의 필드 정의.

dataFormat과 다양한 사용 가능한 디코더에 대한 설명은 Kafka 커넥터 페이지를 참조하세요.

위 Kafka 타입에 더해 Redis 커넥터는 value 필드에 hash 타입을 지원하며, 이는 Redis 해시에 저장된 데이터를 나타내요.

{
    "tableName": ...,
    "schemaName": ...,
    "value": {
        "dataFormat": "hash",
        "fields": [
            ...
       ]
    }
}

타입 매핑 (Type mapping)

Trino와 Redis가 서로 지원하지 않는 타입을 각각 지원하므로, 이 커넥터는 데이터를 읽을 때 일부 타입을 매핑해요. 타입 매핑은 RAW, CSV, JSON, AVRO 파일 형식에 따라 달라요.

행 디코딩 (Row decoding)

데이터를 테이블 컬럼에 매핑하는 데 디코더가 사용돼요.

커넥터는 다음 디코더를 포함해요.

raw: 메시지를 해석하지 않고, 원시 메시지 바이트의 범위를 테이블 컬럼에 매핑.
csv: 메시지를 쉼표로 구분된 메시지로 해석하고, 필드를 테이블 컬럼에 매핑.
json: 메시지를 JSON으로 파싱하고, JSON 필드를 테이블 컬럼에 매핑.
avro: Avro 스키마 기반으로 메시지를 파싱하고, Avro 필드를 테이블 컬럼에 매핑.

참고

테이블에 대한 테이블 정의 파일이 없으면 dummy 디코더가 사용되며, 이는 어떤 컬럼도 노출하지 않아요.

Raw 디코더 (Raw decoder)

raw 디코더는 메시지 또는 키에서 원시 바이트 기반 값을 읽고 Trino 컬럼으로 변환하는 것을 지원해요.

필드에 대해 다음 속성이 지원돼요.

dataFormat - 변환한 데이터 타입의 너비를 선택.
type - Trino 데이터 타입. 지원되는 데이터 타입 목록은 다음 표 참조.
mapping - [:] - 변환할 바이트의 시작·끝 위치(선택).

dataFormat 속성은 변환되는 바이트 수를 선택해요. 없으면 BYTE가 가정돼요. 모든 값은 부호가 있어요.

지원되는 값은 다음과 같아요.

BYTE - 1바이트
SHORT - 2바이트 (빅엔디언)
INT - 4바이트 (빅엔디언)
LONG - 8바이트 (빅엔디언)
FLOAT - 4바이트 (IEEE 754 형식)
DOUBLE - 8바이트 (IEEE 754 형식)

type 속성은 값이 매핑되는 Trino 데이터 타입을 정의해요.

컬럼에 할당된 Trino 타입에 따라 서로 다른 dataFormat 값을 사용할 수 있어요.

Trino 데이터 타입	허용되는 `dataFormat` 값
`BIGINT`	`BYTE`, `SHORT`, `INT`, `LONG`
`INTEGER`	`BYTE`, `SHORT`, `INT`
`SMALLINT`	`BYTE`, `SHORT`
`DOUBLE`	`DOUBLE`, `FLOAT`
`BOOLEAN`	`BYTE`, `SHORT`, `INT`, `LONG`
`VARCHAR` / `VARCHAR(x)`	`BYTE`

다른 타입은 지원하지 않아요.

mapping 속성은 디코딩에 사용되는 키 또는 메시지의 바이트 범위를 지정해요. 콜론으로 구분된 한두 숫자([:])일 수 있어요.

시작 위치만 주어진 경우:

고정 너비 타입의 경우 컬럼은 지정된 dataFormat에 대한 적절한 바이트 수를 사용해요(위 참조).
VARCHAR 값을 디코딩할 때는 시작 위치부터 메시지 끝까지의 모든 바이트를 사용해요.

시작·끝 위치가 모두 주어진 경우:

고정 너비 타입의 경우 크기는 지정된 dataFormat이 사용하는 바이트 수와 같아야 해요.
VARCHAR 데이터 타입의 경우 시작(포함)과 끝(제외) 사이의 모든 바이트를 사용해요.

mapping 속성이 없으면 시작 위치를 0으로 설정하고 끝 위치를 정의하지 않는 것과 같아요.

숫자 데이터 타입(BIGINT, INTEGER, SMALLINT, TINYINT, DOUBLE)의 디코딩 방식은 단순해요. 입력 메시지에서 바이트 시퀀스를 읽고 다음 중 하나에 따라 디코딩해요.

빅엔디언 인코딩 (정수 타입)
DOUBLE의 IEEE 754 형식

디코딩된 바이트 시퀀스의 길이는 dataFormat에 의해 암시돼요.

VARCHAR 데이터 타입의 경우 바이트 시퀀스는 UTF-8 인코딩에 따라 해석돼요.

CSV 디코더 (CSV decoder)

CSV 디코더는 메시지 또는 키를 나타내는 바이트를 UTF-8 인코딩을 사용해 문자열로 변환하고, 결과를 쉼표로 구분된 값의 연결로 해석해요.

필드에 대해 type과 mapping 속성을 정의해야 해요.

type - Trino 데이터 타입. 지원되는 데이터 타입 목록은 다음 표 참조.
mapping - CSV 레코드에서 필드의 인덱스.

dataFormat과 formatHint 속성은 지원되지 않으므로 생략해야 해요.

Trino 데이터 타입	디코딩 규칙
`BIGINT`, `INTEGER`, `SMALLINT`, `TINYINT`	Java `Long.parseLong()`으로 디코딩
`DOUBLE`	Java `Double.parseDouble()`으로 디코딩
`BOOLEAN`	"true" 문자 시퀀스는 `true`로 매핑. 다른 문자 시퀀스는 `false`로 매핑
`VARCHAR` / `VARCHAR(x)`	있는 그대로 사용

다른 타입은 지원하지 않아요.

JSON 디코더 (JSON decoder)

JSON 디코더는 메시지 또는 키를 나타내는 바이트를 RFC 4627에 따라 Javascript Object Notation(JSON)으로 변환해요. 메시지 또는 키는 배열이나 단순 타입이 아닌 JSON 객체로 변환되어야 해요.

필드에 대해 다음 속성이 지원돼요.

type - 컬럼의 Trino 데이터 타입.
dataFormat - 컬럼에 사용할 필드 디코더.
mapping - JSON 객체에서 필드를 선택하는 슬래시 구분 필드 이름 목록.
formatHint - custom-date-time에서만.

JSON 디코더는 표준 테이블 컬럼에 사용되는 _default와 날짜·시간 기반 타입용 여러 디코더를 포함한 여러 필드 디코더를 지원해요.

다음 표는 type에 쓸 수 있고 일치하는 필드 디코더(dataFormat 속성으로 지정)가 있는 Trino 데이터 타입을 나열해요.

Trino 데이터 타입	허용되는 `dataFormat` 값
`BIGINT`, `INTEGER`, `SMALLINT`, `TINYINT`, `DOUBLE`, `BOOLEAN`, `VARCHAR`, `VARCHAR(x)`	기본 필드 디코더 (`dataFormat` 속성 생략)
`DATE`	`custom-date-time`, `iso8601`
`TIME`	`custom-date-time`, `iso8601`, `milliseconds-since-epoch`, `seconds-since-epoch`
`TIME WITH TIME ZONE`	`custom-date-time`, `iso8601`
`TIMESTAMP`	`custom-date-time`, `iso8601`, `rfc2822`, `milliseconds-since-epoch`, `seconds-since-epoch`
`TIMESTAMP WITH TIME ZONE`	`custom-date-time`, `iso8601`, `rfc2822`, `milliseconds-since-epoch`, `seconds-since-epoch`

다른 타입은 지원하지 않아요.

기본 필드 디코더 (Default field decoder)

이것은 표준 필드 디코더예요. 모든 Trino 물리 데이터 타입을 지원해요. 필드 값은 JSON 변환 규칙에 따라 boolean, long, double, string 값으로 변환돼요. 이 디코더는 날짜·시간 기반이 아닌 컬럼에 사용해야 해요.

날짜·시간 디코더 (Date and time decoders)

JSON 객체의 값을 Trino DATE, TIME, TIME WITH TIME ZONE, TIMESTAMP, TIMESTAMP WITH TIME ZONE 컬럼으로 변환하려면 필드 정의의 dataFormat 속성을 사용해 특수 디코더를 선택해요.

iso8601 - 텍스트 기반. 텍스트 필드를 ISO 8601 타임스탬프로 파싱.
rfc2822 - 텍스트 기반. 텍스트 필드를 RFC 2822 타임스탬프로 파싱.
custom-date-time - 텍스트 기반. formatHint 속성으로 지정된 Joda 형식 패턴에 따라 텍스트 필드를 파싱. 형식 패턴은 DateTimeFormat 패턴을 따라야 해요.
milliseconds-since-epoch - 숫자 기반. 텍스트나 숫자를 에포크 이후 밀리초 수로 해석.
seconds-since-epoch - 숫자 기반. 텍스트나 숫자를 에포크 이후 초 수로 해석.

TIMESTAMP WITH TIME ZONE과 TIME WITH TIME ZONE 데이터 타입의 경우, 디코딩된 값에 타임존 정보가 있으면 Trino 값으로 사용돼요. 그렇지 않으면 결과 타임존이 UTC로 설정돼요.

Avro 디코더 (Avro decoder)

Avro 디코더는 메시지 또는 키를 나타내는 바이트를 스키마 기반으로 Avro 형식으로 변환해요. 메시지에는 Avro 스키마가 내장되어 있어야 해요. Trino는 스키마 없는 Avro 디코딩을 지원하지 않아요.

Avro 디코더를 사용하는 어떤 키나 메시지에도 dataSchema를 정의해야 해요. Avro 디코더는 디코딩해야 하는 메시지의 유효한 Avro 스키마 파일 위치를 가리켜야 해요. 이 위치는 원격 웹 서버(예: dataSchema: 'http://example.org/schema/avro_data.avsc')나 로컬 파일 시스템(예: dataSchema: '/usr/local/schema/avro_data.avsc')일 수 있어요. 이 위치에 Trino 클러스터에서 접근할 수 없으면 디코더가 실패해요.

다음 속성이 지원돼요.

name - Trino 테이블의 컬럼 이름.
type - 컬럼의 Trino 데이터 타입.
mapping - Avro 스키마에서 필드를 선택하는 슬래시 구분 필드 이름 목록. mapping에 지정된 필드가 원래 Avro 스키마에 없으면 읽기 연산이 NULL을 반환.

다음 표는 해당 Avro 필드 타입에 대해 type에 쓸 수 있는 지원 Trino 타입을 나열해요.

Trino 데이터 타입	허용되는 Avro 데이터 타입
`BIGINT`	`INT`, `LONG`
`DOUBLE`	`DOUBLE`, `FLOAT`
`BOOLEAN`	`BOOLEAN`
`VARCHAR` / `VARCHAR(x)`	`STRING`
`VARBINARY`	`FIXED`, `BYTES`
`ARRAY`	`ARRAY`
`MAP`	`MAP`

다른 타입은 지원하지 않아요.

Avro 스키마 진화 (Avro schema evolution)

Avro 디코더는 하위 호환(backward compatibility)을 통한 스키마 진화를 지원해요. 하위 호환을 통해 더 오래된 스키마로 만든 Avro 데이터를 더 새로운 스키마로 읽을 수 있어요. Avro 스키마의 어떤 변경도 Trino의 토픽 정의 파일에 반영되어야 해요. 새로 추가되거나 이름이 바뀐 필드는 Avro 스키마 파일에 기본값이 있어야 해요.

스키마 진화 동작은 다음과 같아요.

새 스키마에 추가된 컬럼: 더 오래된 스키마로 만든 데이터는 테이블이 새 스키마를 사용할 때 기본 값을 만들어요.
새 스키마에서 제거된 컬럼: 더 오래된 스키마로 만든 데이터는 제거된 컬럼의 데이터를 더 이상 출력하지 않아요.
새 스키마에서 이름이 바뀐 컬럼: 컬럼을 제거하고 새로 추가하는 것과 동일하며, 더 오래된 스키마로 만든 데이터는 테이블이 새 스키마를 사용할 때 기본 값을 만들어요.
새 스키마에서 컬럼의 타입 변경: Avro가 타입 강제 변환을 지원하면 변환이 일어나요. 호환되지 않는 타입에는 오류가 발생해요.

SQL 지원 (SQL support)

이 커넥터는 Redis의 데이터와 메타데이터에 접근하는 전역적으로 사용 가능한 문장과 읽기 연산 문장을 제공해요.

성능 (Performance)

커넥터에는 다음 섹션에 자세히 설명된 여러 성능 개선이 포함돼요.

푸시다운 (Pushdown)

참고

커넥터는 성능이 개선될 수 있는 곳에서 푸시다운을 수행하지만, 정확성을 보존하기 위해 연산이 푸시다운되지 않을 수 있어요. 연산의 푸시다운이 더 나은 성능을 만들 수 있지만 정확성을 위험에 빠뜨릴 때, 커넥터는 정확성을 우선해요.

프레디킷 푸시다운 지원 (Predicate pushdown support)

커넥터는 string 타입의 키 푸시다운만 지원하고 zset 타입은 지원하지 않아요. 테이블 정의 파일에 여러 키 필드가 정의되면 키 푸시다운이 지원되지 않아요.

커넥터는 IN이나 = 같은 동등성 프레디킷의 푸시다운을 지원해요. != 같은 부등식 프레디킷과 > 같은 범위 프레디킷은 푸시다운되지 않아요.

-- Not pushed down
SELECT * FROM nation WHERE redis_key > 'CANADA';
-- Pushed down
SELECT * FROM nation WHERE redis_key = 'CANADA';
SELECT * FROM nation WHERE redis_key IN ('CANADA', 'POLAND');

더 알아보기 (Learn more)

Redis 커넥터의 디코더와 테이블 정의는 Kafka 커넥터와 밀접하게 연관돼 있어요. 함께 보면 이해가 쉬워요.