SingleStore 커넥터
SingleStore 커넥터 (SingleStore connector)
SingleStore 커넥터는 Trino 쿼리에서 외부 SingleStore 데이터베이스의 데이터를 읽고 쓸 수 있게 해줍니다. 이 커넥터 덕분에 여러 SingleStore 인스턴스의 데이터를 하나의 쿼리로 조합할 수 있어요.
출처: 문서
본문
요구 사항 (Requirements)
SingleStore에 연결하려면 다음이 필요합니다:
- SingleStore 서버 (5.7 이상, MySQL 호환 모드).
- Trino 코디네이터와 워커에서 SingleStore로의 네트워크 접근.
설정 (Configuration)
SingleStore 커넥터를 example 카탈로그로 설정하려면 etc/catalog에 example.properties라는 파일을 만들고 다음 연결 속성을 넣어주세요:
connector.name=singlestore
connection-url=jdbc:singlestore://example.net:3306/
connection-user=root
connection-password=secret
connection-url은 JDBC 드라이버에 전달할 연결 정보와 파라미터를 정의합니다. 커넥터는 SingleStore JDBC 드라이버를 사용하며, 연결 사용자 이름과 비밀번호가 필요합니다. 시크릿 (secrets)을 사용하면 카탈로그 속성 파일에 실제 값을 넣지 않고도 자격 증명을 관리할 수 있습니다.
데이터 소스 인증 (Data source authentication)
커넥터는 데이터 소스 연결용 자격 증명을 여러 방법으로 제공할 수 있습니다:
- 커넥터 설정 파일에 inline으로
- 별도의 properties 파일로
- 키 스토어 파일로
- Trino에 연결할 때 추가 자격 증명 (extra credentials)으로
시크릿 (secrets)을 활용하면 카탈로그 속성 파일에 민감한 값을 저장하지 않을 수 있어요.
여러 SingleStore 서버 (Multiple SingleStore servers)
여러 SingleStore 서버에 연결하려면 커넥터를 별도의 카탈로그로 또 설정하세요. 예를 들어 sales.properties라는 파일을 만들면 Trino가 sales라는 카탈로그를 생성합니다.
일반 설정 속성 (General configuration properties)
다음 표는 커넥터의 일반적인 카탈로그 설정 속성을 설명합니다:
| 속성 이름 | 설명 | 기본값 |
|---|---|---|
case-insensitive-name-matching |
대소문자 구분 없는 스키마/테이블 이름 지원 여부. | false |
case-insensitive-name-matching.cache-ttl |
대소문자 구분 없는 이름이 캐시되는 기간. | 1m |
case-insensitive-name-matching.config-file |
이름 매핑 설정 파일(JSON) 경로. | null |
case-insensitive-name-matching.config-file.refresh-period |
이름 매핑 파일 변경 확인 주기. | 0s |
metadata.cache-ttl |
테이블/컬럼 통계를 포함한 메타데이터 캐시 기간. | 0s |
metadata.cache-missing |
메타데이터가 없음을 캐시할지 여부. | false |
metadata.schemas.cache-ttl |
스키마 메타데이터 캐시 기간. | metadata.cache-ttl 값 |
metadata.tables.cache-ttl |
테이블 메타데이터 캐시 기간. | metadata.cache-ttl 값 |
metadata.statistics.cache-ttl |
테이블 통계 캐시 기간. | metadata.cache-ttl 값 |
metadata.cache-maximum-size |
메타데이터 캐시에 저장되는 최대 객체 수. | 10000 |
write.batch-size |
배치 실행에서의 최대 명령문 수. 기본값에서 바꾸지 마세요. | 1000 |
데이터 유형 매핑 (Type mapping)
Trino와 SingleStore는 서로 지원하지 않는 유형이 있으므로, 이 커넥터는 데이터를 읽거나 쓸 때 일부 유형을 변환합니다. 각 방향의 매핑은 아래 표를 참고하세요.
SingleStore에서 Trino로의 유형 매핑:
| SingleStore 유형 | Trino 유형 |
|---|---|
BOOLEAN |
BOOLEAN |
TINYINT |
TINYINT |
SMALLINT |
SMALLINT |
INTEGER |
INTEGER |
BIGINT |
BIGINT |
DOUBLE |
DOUBLE |
FLOAT |
REAL |
DECIMAL(p, s) |
DECIMAL(p, s) |
CHAR(n) |
CHAR(n) |
TINYTEXT |
VARCHAR(255) |
TEXT |
VARCHAR(65535) |
MEDIUMTEXT |
VARCHAR(16777215) |
LONGTEXT |
VARCHAR |
VARCHAR(n) |
VARCHAR(n) |
LONGBLOB |
VARBINARY |
DATE |
DATE |
TIME |
TIME(0) |
TIME(6) |
TIME(6) |
DATETIME |
TIMESTAMP(0) |
DATETIME(6) |
TIMESTAMP(6) |
JSON |
JSON |
그 외 유형은 지원되지 않습니다.
Trino에서 SingleStore로의 유형 매핑:
| Trino 유형 | SingleStore 유형 |
|---|---|
BOOLEAN |
BOOLEAN |
TINYINT |
TINYINT |
SMALLINT |
SMALLINT |
INTEGER |
INTEGER |
BIGINT |
BIGINT |
DOUBLE |
DOUBLE |
REAL |
FLOAT |
DECIMAL(p, s) |
DECIMAL(p, s) |
CHAR(n) |
CHAR(n) |
VARCHAR(65535) |
TEXT |
VARCHAR(16777215) |
MEDIUMTEXT |
VARCHAR |
LONGTEXT |
VARCHAR(n) |
VARCHAR(n) |
VARBINARY |
LONGBLOB |
DATE |
DATE |
TIME(0) |
TIME |
TIME(6) |
TIME(6) |
TIMESTAMP(0) |
DATETIME |
TIMESTAMP(6) |
DATETIME(6) |
JSON |
JSON |
그 외 유형은 지원되지 않습니다.
유형 매핑 설정 속성 (Type mapping configuration properties)
다음 속성으로 연결된 데이터 소스의 유형을 Trino 유형으로 매핑하는 방식과 메타데이터 캐시 방식을 설정할 수 있습니다:
| 속성 이름 | 설명 | 기본값 |
|---|---|---|
unsupported-type-handling |
지원되지 않는 컬럼 유형 처리 방식: IGNORE(컬럼 접근 불가) 또는 CONVERT_TO_VARCHAR(무제한 VARCHAR로 변환). 해당 카탈로그 세션 속성은 unsupported_type_handling. |
IGNORE |
jdbc-types-mapped-to-varchar |
무제한 VARCHAR로 변환할 유형의 쉼표 구분 목록을 강제 매핑. |
— |
SQL 지원 (SQL support)
커넥터는 SingleStore 데이터베이스의 데이터와 메타데이터에 대해 읽기/쓰기 접근을 제공합니다. 전역 사용 가능 명령문과 읽기 연산 명령문에 더해 다음 기능을 지원합니다:
- INSERT — 비트랜잭션 INSERT 참고
- UPDATE — UPDATE 제한 참고
- DELETE — DELETE 제한 참고
- TRUNCATE
- CREATE TABLE
- CREATE TABLE AS
- ALTER TABLE — ALTER TABLE RENAME TO 제한 참고
- DROP TABLE
- CREATE SCHEMA
- DROP SCHEMA
- 프로시저
비트랜잭션 INSERT (Non-transactional INSERT)
커넥터는 INSERT 문으로 행 추가를 지원합니다. 기본적으로 데이터는 임시 테이블에 먼저 기록됩니다. insert.non-transactional-insert.enabled 카탈로그 속성 또는 해당 non_transactional_insert 카탈로그 세션 속성을 true로 설정하면 이 단계를 건너뛰고 대상 테이블에 직접 기록해 성능을 높일 수 있습니다.
이 속성을 켜면 드물게 insert 작업 중 예외가 발생할 때 데이터가 손상될 수 있습니다. 트랜잭션이 비활성화되므로 롤백이 불가능합니다.
UPDATE 제한 (UPDATE limitation)
상수 할당과 상수 조건을 가진 UPDATE 문만 지원합니다. 예를 들어 다음 문은 값이 상수이므로 지원됩니다:
UPDATE table SET col1 = 1 WHERE col3 = 1
산술 표현식, 함수 호출 등 비상수 UPDATE 문은 지원되지 않습니다. 예를 들어 다음 문은 산술 표현식을 SET에 사용할 수 없으므로 지원되지 않습니다:
UPDATE table SET col1 = col2 + 2 WHERE col3 = 1
한 행의 모든 컬럼 값을 동시에 갱신할 수는 없습니다. 3개 컬럼 테이블에서 다음 문은 지원되지 않습니다:
UPDATE table SET col1 = 1, col2 = 2, col3 = 3 WHERE col3 = 1
DELETE 제한 (DELETE limitation)
WHERE 절이 지정되면 해당 절의 조건을 데이터 소스에 완전히 푸시다운할 수 있을 때만 DELETE가 동작합니다.
ALTER TABLE RENAME TO 제한 (ALTER TABLE RENAME TO limitation)
여러 스키마에 걸친 테이블 이름 변경은 지원하지 않습니다. 예를 들어 다음 문은 지원됩니다:
ALTER TABLE example.schema_one.table_one RENAME TO example.schema_one.table_two
다음 문은 스키마를 넘어 이름을 바꾸려 하므로 지원되지 않습니다:
ALTER TABLE example.schema_one.table_one RENAME TO example.schema_two.table_two
프로시저 (Procedures)
system.flush_metadata_cache()
JDBC 메타데이터 캐시를 비웁니다. 예를 들어 다음 시스템 호출은 example 카탈로그의 모든 스키마에 대한 메타데이터 캐시를 비웁니다:
USE example.example_schema;
CALL system.flush_metadata_cache();
system.execute('query')
execute 프로시저는 연결된 데이터 소스에서 쿼리를 직접 실행하게 해줍니다. 쿼리는 연결된 데이터 소스의 지원 문법을 사용해야 합니다. Trino에 없는 기능에 접근하거나, 결과 집합을 반환하지 않아 query나 raw_query 패스스루 테이블 함수로 사용할 수 없는 쿼리를 실행할 때 유용합니다. 대표적인 사례는 객체를 생성/수정하는 명령문으로, 제약 조건, 기본값, 자동 식별자 생성, 인덱스 같은 네이티브 기능이 필요할 때입니다. 데이터를 삽입/갱신/삭제하면서 결과를 반환하지 않는 명령문도 호출할 수 있습니다.
쿼리 텍스트는 Trino가 파싱하지 않고 그대로 전달하므로, 연결된 데이터 소스의 보안/접근 제어만 적용됩니다.
다음 예제는 example 카탈로그의 example_schema를 현재 데이터베이스로 설정한 뒤, 그 스키마에서 프로시저를 호출해 your_table 테이블의 your_column에서 기본값을 제거합니다:
USE example.example_schema;
CALL system.execute(query => 'ALTER TABLE your_table ALTER COLUMN your_column DROP DEFAULT');
특정 데이터베이스가 이 문법을 지원하는지 확인하고, 연결된 데이터베이스 및 버전 문서에 맞게 조정하세요.
성능 (Performance)
커넥터는 다음 섹션에 설명된 여러 성능 개선을 포함합니다.
푸시다운 (Pushdown)
커넥터는 다음 연산에 대해 푸시다운을 지원합니다:
- 조인 푸시다운
- LIMIT 푸시다운
- Top-N 푸시다운
커넥터는 성능이 향상될 수 있는 곳에서 푸시다운을 수행하지만, 정확성을 지키기 위해 일부 연산은 푸시다운되지 않을 수 있습니다. 푸시다운이 성능은 좋지만 정확성을 위험하게 한다면 커넥터는 정확성을 우선합니다.
조인 푸시다운 (Join pushdown)
join-pushdown.enabled 카탈로그 설정 속성 또는 join_pushdown_enabled 카탈로그 세션 속성이 커넥터의 조인 연산 푸시다운 여부를 제어합니다. 기본값은 false이며, 조인 푸시다운을 켜면 일부 쿼리 성능에 부정적 영향을 줄 수 있습니다.
조건 푸시다운 지원 (Predicate pushdown support)
커넥터는 CHAR나 VARCHAR 같은 텍스트 유형 컬럼에 대한 조건 푸시다운을 지원하지 않습니다. 데이터 소스가 문자열을 대소문자 구분 없이 비교할 수 있으므로 결과 정확성을 보장하기 위해서입니다.
다음 예제에서 name은 VARCHAR 유형 컬럼이므로 두 쿼리 모두 조건이 푸시다운되지 않습니다:
SELECT * FROM nation WHERE name > 'CANADA';
SELECT * FROM nation WHERE name = 'CANADA';
더 알아보기 (Learn more)
SingleStore 커넥터로 다른 데이터 소스와 데이터를 조합해보세요. 커넥터의 일반적인 개념은 커넥터 개요 문서에서 확인할 수 있어요.