cqlsh: CQL 셸

cqlsh: CQL 셸

cqlsh는 CQL(Cassandra Query Language)을 사용해 Cassandra와 상호작용하기 위한 명령줄 인터페이스예요. 모든 Cassandra 패키지에 포함되어 있으며, cassandra 실행 파일 옆의 bin/ 디렉터리에서 찾을 수 있습니다. cqlsh는 Python 네이티브 프로토콜 드라이버로 구현되며, 지정된 단일 노드에 연결합니다.

출처: 문서

본문

호환성 (Compatibility)

일반적으로 주어진 버전의 cqlsh는 그것과 함께 릴리스된 Cassandra 버전에서만 작동한다는 것이 보장됩니다. 어떤 경우 cqlsh는 더 오래되거나 더 새로운 Cassandra 버전에서 작동할 수 있지만, 이는 공식적으로 지원되지 않습니다.

선택적 의존성 (Optional Dependencies)

cqlsh는 모든 필수 의존성과 함께 제공됩니다. 하지만 cqlsh의 기능을 개선하기 위해 설치할 수 있는 몇 가지 선택적 의존성이 있습니다.

pytz

기본적으로 cqlsh는 모든 타임스탬프를 UTC 시간대로 표시합니다. Python 3.9 이상에서는 cqlshrc의 timezone 옵션을 수정하거나 TZ 환경 변수를 설정해 타임스탬프를 다른 시간대로 표시할 수 있습니다. 하지만 Python 3.8 이하는 pytz 라이브러리 설치도 필요해요.

cython

cython을 설치하면 cqlsh의 COPY 연산 성능이 개선될 수 있습니다. 이것은 COPY 성능의 중심이 되는 python 모듈을 컴파일합니다.

cqlshrc

cqlshrc 파일은 cqlsh의 구성 옵션을 담고 있습니다. 기본적으로 파일은 사용자 홈 디렉터리의 ~/.cassandra/cqlshrc에 있지만, --cqlshrc 옵션으로 커스텀 위치를 지정할 수 있어요.

예제 구성 값과 문서는 tarball 설치의 conf/cqlshrc.sample 파일에서 찾을 수 있습니다. 최신 버전의 cqlshrc 파일도 온라인에서 볼 수 있어요.

자격 증명 (credentials)

credentials 파일은 cqlsh의 사용자 이름과 비밀번호를 포함합니다. 사용자 이름과 비밀번호는 cqlshrc 파일의 [auth_provider] 섹션의 classname과 일치하는 이름의 섹션에 위치해야 합니다. credentials 파일은 사용자가 소유해야 하고 다른 누구도 파일을 읽을 권한이 없어야 해요.

예제 구성 값과 문서는 tarball 설치의 conf/credentials.sample 파일에서 찾을 수 있습니다.

CQL 히스토리

실행하는 모든 CQL 명령은 히스토리 파일에 기록됩니다. 기본적으로 CQL 히스토리는 ~/.cassandra/cql_history에 기록됩니다. 환경 변수 CQL_HISTORY를 ~/some/other/path/to/cqlsh_history처럼 설정해 이 기본값을 변경할 수 있어요(여기서 cqlsh_history는 파일). 히스토리 파일의 모든 상위 디렉터리는 존재하지 않으면 생성됩니다. 히스토리를 유지하고 싶지 않다면 CQL_HISTORY를 /dev/null로 설정하면 됩니다. 이는 --disable-history 명령줄 옵션이나 cqlshrc 파일로도 제어할 수 있어요. 히스토리 비활성화는 Cassandra 4.0부터 지원됩니다.

명령줄 옵션

Usage: cqlsh.py [options] [host [port]]

CQL Shell for Apache Cassandra

Options:

--version
show program's version number and exit

-h --help
show this help message and exit

-C --color
Always use color output

--no-color
Never use color output

--browser=BROWSER
The browser to use to display CQL help, where BROWSER can be: one of the supported browsers in docs.python.org/3/library/webbrowser.html. browser path followed by %s, example: /usr/bin/google-chrome-stable %s

--ssl
Use SSL

-u USERNAME --username=USERNAME
Authenticate as user.

-p PASSWORD --password=PASSWORD
Authenticate using password.

-k KEYSPACE --keyspace=KEYSPACE
Authenticate to the given keyspace.

-f FILE --file=FILE
Execute commands from FILE, then exit

--debug
Show additional debugging information

--coverage
Collect coverage data

--encoding=ENCODING
Specify a non-default encoding for output. (Default: utf-8)

--cqlshrc=CQLSHRC
Specify an alternative cqlshrc file location.

--credentials=CREDENTIALS
Specify an alternative credentials file location.

--cqlversion=CQLVERSION
Specify a particular CQL version, by default the highest version supported by the server will be used. Examples: "3.0.3", "3.1.0"

--protocol-version=PROTOCOL_VERSION
Specify a specific protcol version otherwise the client will default and downgrade as necessary

-e EXECUTE --execute=EXECUTE
Execute the statement and quit.

--connect-timeout=CONNECT_TIMEOUT
Specify the connection timeout in seconds (default: 5 seconds).

--request-timeout=REQUEST_TIMEOUT
Specify the default request timeout in seconds (default: 10 seconds).

-t, --tty
Force tty mode (command prompt).

-v --v
Print the current version of cqlsh.

특수 명령

일반 CQL 문을 지원하는 것 외에도 cqlsh는 CQL의 일부가 아닌 여러 특수 명령을 지원합니다. 아래에 자세히 설명합니다.

CONSISTENCY

사용법: CONSISTENCY <consistency level>

이후 연산의 일관성 수준을 설정합니다. 유효한 인자는:

• ANY
• ONE
• TWO
• THREE
• QUORUM
• ALL
• LOCAL_QUORUM
• LOCAL_ONE
• SERIAL
• LOCAL_SERIAL

SERIAL CONSISTENCY

사용법: SERIAL CONSISTENCY <consistency level>

이후 연산의 직렬 일관성 수준을 설정합니다. 유효한 인자는:

• SERIAL
• LOCAL_SERIAL

직렬 일관성 수준은 조건부 업데이트(IF 조건이 있는 INSERT, UPDATE, DELETE)에서만 사용됩니다. 그러한 연산에서 직렬 일관성 수준은 직렬 단계("paxos" 단계)의 일관성 수준을 정의하고, 정상 일관성 수준은 "learn" 단계의 일관성을 정의합니다. 즉 어떤 유형의 읽기가 업데이트를 즉시 보는 것이 보장되는지를 정의해요. 예를 들어 조건부 쓰기의 일관성 수준이 QUORUM이면(그리고 성공하면) QUORUM 읽기가 그 쓰기를 보는 것이 보장됩니다. 하지만 그 쓰기의 정상 일관성 수준이 ANY이면 SERIAL 일관성 수준의 읽기만 그것을 보는 것이 보장됩니다(ALL 일관성의 읽기조차 충분하지 않을 수 있어요).

SHOW VERSION

사용 중인 cqlsh, Cassandra, CQL, 네이티브 프로토콜 버전을 출력합니다. 예:

cqlsh> SHOW VERSION
[cqlsh 5.0.1 | Cassandra 3.8 | CQL spec 3.4.2 | Native protocol v4]

SHOW HOST

cqlsh가 연결된 Cassandra 노드의 IP 주소와 포트를 클러스터 이름과 함께 출력합니다. 예:

cqlsh> SHOW HOST
Connected to Prod_Cluster at 192.0.0.1:9042.

SHOW REPLICAS

주어진 토큰과 키스페이스에 대한 리플리카인 Cassandra 노드의 IP 주소를 출력합니다. 이 명령은 Cassandra 4.2부터 사용 가능합니다.

사용법: SHOW REPLICAS <token> (<keyspace>)

예제 사용:

cqlsh> SHOW REPLICAS 95
['192.0.0.1', '192.0.0.2']

SHOW SESSION

특정 추적 세션을 보기 좋게 출력합니다.

사용법: SHOW SESSION <session id>

예제 사용:

cqlsh> SHOW SESSION 95ac6470-327e-11e6-beca-dfb660d92ad8

Tracing session: 95ac6470-327e-11e6-beca-dfb660d92ad8

 activity                                                  | timestamp                  | source    | source_elapsed | client
-----------------------------------------------------------+----------------------------+-----------+----------------+-----------
                                        Execute CQL3 query | 2016-06-14 17:23:13.979000 | 127.0.0.1 |              0 | 127.0.0.1
 Parsing SELECT * FROM system.local; [SharedPool-Worker-1] | 2016-06-14 17:23:13.982000 | 127.0.0.1 |           3843 | 127.0.0.1
...

SOURCE

파일의 내용을 읽고 각 줄을 CQL 문 또는 특수 cqlsh 명령으로 실행합니다.

사용법: SOURCE <string filename>

예제 사용:

cqlsh> SOURCE '/home/calvinhobbs/commands.cql'

CAPTURE

명령 출력을 캡처해서 지정된 파일에 추가하기 시작합니다. 캡처 중에는 콘솔에 출력이 표시되지 않습니다.

사용법:

CAPTURE '<file>';
CAPTURE OFF;
CAPTURE;

즉 추가할 파일 경로는 문자열 리터럴로 지정해야 합니다. 경로는 현재 작업 디렉터리를 기준으로 해석됩니다. $HOME을 나타내는 물결표 약칭 표기법('~/mydir')이 지원됩니다.

쿼리 결과 출력만 캡처됩니다. 오류와 cqlsh 전용 명령의 출력은 cqlsh 세션에 계속 표시됩니다.

캡처를 중지하고 cqlsh 세션에서 다시 표시하려면 CAPTURE OFF를 사용하세요.

현재 캡처 구성을 확인하려면 인자 없이 CAPTURE를 사용합니다.

HELP

cqlsh 명령에 대한 정보를 제공합니다. 사용 가능한 주제를 보려면 인자 없이 HELP를 입력하세요. 주제에 대한 도움말을 보려면 HELP <topic>을 사용합니다. 도움말 표시에 사용할 브라우저를 제어하는 --browser 인자도 참고하세요.

HISTORY

서버에서 실행된 지난 n개의 cqlsh 명령을 화면에 출력합니다. 지정하지 않으면 줄 수의 기본값은 50입니다. n은 현재 CQL 세션에 대해 설정되므로 예를 들어 10으로 설정하면 그 시점부터 반환되는 마지막 명령은 최대 10개입니다.

사용법:

HISTORY <n>

TRACING

쿼리에 대한 추적을 활성화 또는 비활성화합니다. 추적이 활성화되면 쿼리가 완료되는 즉시 쿼리 중 이벤트의 추적이 출력됩니다.

사용법:

TRACING ON
TRACING OFF

PAGING

읽기 쿼리에 대한 페이징을 활성화, 비활성화 또는 페이지 크기를 설정합니다. 페이징이 활성화되면 한 번에 한 페이지의 데이터만 가져오고 다음 페이지를 가져오라는 프롬프트가 나타납니다. 일반적으로 대화형 세션에서 한 번에 많은 양의 데이터를 가져와 출력하는 것을 피하기 위해 페이징을 활성화해 두는 것이 좋습니다.

사용법:

PAGING ON
PAGING OFF
PAGING <page size in rows>

EXPAND

행의 세로 출력을 활성화 또는 비활성화합니다. 많은 컬럼을 가져오거나 단일 컬럼의 내용이 클 때 EXPAND를 활성화하는 것이 유용합니다.

사용법:

EXPAND ON
EXPAND OFF

LOGIN

현재 세션에 대해 지정된 Cassandra 사용자로 인증합니다.

사용법:

LOGIN <username> [<password>]

EXIT

현재 세션을 끝내고 cqlsh 프로세스를 종료합니다.

사용법:

EXIT
QUIT

CLEAR

콘솔을 지웁니다.

사용법:

CLEAR
CLS

DESCRIBE

스키마 요소 또는 클러스터에 대한 설명(보통 일련의 DDL 문)을 출력합니다. 스키마의 전체 또는 일부를 덤프하는 데 유용합니다.

사용법:

DESCRIBE CLUSTER
DESCRIBE SCHEMA
DESCRIBE KEYSPACES
DESCRIBE KEYSPACE <keyspace name>
DESCRIBE TABLES
DESCRIBE TABLE <table name>
DESCRIBE INDEX <index name>
DESCRIBE MATERIALIZED VIEW <view name>
DESCRIBE TYPES
DESCRIBE TYPE <type name>
DESCRIBE FUNCTIONS
DESCRIBE FUNCTION <function name>
DESCRIBE AGGREGATES
DESCRIBE AGGREGATE <aggregate function name>

이 명령 중 어느 것이든 DESCRIBE 대신 DESC를 사용할 수 있습니다.

DESCRIBE CLUSTER 명령은 클러스터 이름과 파티셔너를 출력합니다:

cqlsh> DESCRIBE CLUSTER

Cluster: Test Cluster
Partitioner: Murmur3Partitioner

DESCRIBE SCHEMA 명령은 전체 스키마를 재생성하는 데 필요한 DDL 문을 출력합니다. 이는 클러스터를 복제하거나 백업에서 복원하기 위해 스키마를 덤프할 때 특히 유용합니다.

COPY TO

테이블에서 CSV 파일로 데이터를 복사합니다.

사용법:

COPY <table name> [(<column>, ...)] TO <file name> WITH <copy option> [AND <copy option> ...]

컬럼이 지정되지 않으면 테이블의 모든 컬럼이 CSV 파일로 복사됩니다. 복사할 컬럼의 부분 집합은 테이블 이름 뒤에 괄호로 감싼 쉼표로 구분된 컬럼 이름 목록을 추가해 지정할 수 있어요.

<file name>은 대상 파일의 경로를 나타내는 문자열 리터럴(작은따옴표 포함)이어야 합니다. 또한 (작은따옴표 없이) 특수 값 STDOUT일 수도 있으며, 이 경우 CSV를 stdout으로 출력합니다.

COPY TO와 COPY FROM 모두에 적용되는 옵션은 shared-copy-options를 참고하세요.

COPY TO 옵션

MAXREQUESTS 동시에 가져올 최대 토큰 범위 수. 기본값은 6.

PAGESIZE 단일 페이지에서 가져올 행 수. 기본값은 1000.

PAGETIMEOUT 기본적으로 페이지 타임아웃은 페이지 크기 1000개 항목당 10초이거나, 페이지 크기가 더 작으면 10초입니다.

BEGINTOKEN, ENDTOKEN 내보낼 토큰 범위. 기본값은 전체 링 내보내기.

MAXOUTPUTSIZE 줄 수로 측정된 출력 파일의 최대 크기. 이 최대값을 넘으면 출력 파일이 세그먼트로 분할됩니다. -1은 무제한이며 기본값입니다.

ENCODING 문자에 사용되는 인코딩. 기본값은 utf8.

COPY FROM

CSV 파일에서 테이블로 데이터를 복사합니다.

사용법:

COPY <table name> [(<column>, ...)] FROM <file name> WITH <copy option> [AND <copy option> ...]

컬럼이 지정되지 않으면 CSV 파일의 모든 컬럼이 테이블로 복사됩니다. 복사할 컬럼의 부분 집합은 테이블 이름 뒤에 괄호로 감싼 쉼표로 구분된 컬럼 이름 목록을 추가해 지정할 수 있어요.

<file name>은 소스 파일의 경로를 나타내는 문자열 리터럴(작은따옴표 포함)이어야 합니다. 또한 (작은따옴표 없이) 특수 값 STDIN일 수도 있으며, 이 경우 stdin에서 CSV 데이터를 읽습니다.

COPY TO와 COPY FROM 모두에 적용되는 옵션은 shared-copy-options를 참고하세요.

COPY FROM 옵션

INGESTRATE 초당 처리할 최대 행 수. 기본값은 100000.

MAXROWS 가져올 최대 행 수. -1은 무제한이며 기본값입니다.

SKIPROWS 건너뛸 처음 몇 행. 기본값은 0.

SKIPCOLS 무시할 쉼표로 구분된 컬럼 이름 목록. 기본적으로 건너뛰는 컬럼은 없습니다.

MAXPARSEERRORS 무시할 전역 최대 파싱 오류 수. -1은 무제한이며 기본값입니다.

MAXINSERTERRORS 무시할 전역 최대 삽입 오류 수. -1은 무제한입니다. 기본값은 1000.

ERRFILE = 가져올 수 없었던 모든 행을 저장할 파일. 기본적으로 <ks>_<table>은 키스페이스, <table>은 테이블 이름인 import_<ks>_<table>.err입니다.

MAXBATCHSIZE 단일 배치로 삽입되는 최대 행 수. 기본값은 20.

MINBATCHSIZE 단일 배치로 삽입되는 최소 행 수. 기본값은 10.

CHUNKSIZE 한 번에 메인 프로세스에서 자식 워커 프로세스로 전달되는 행 수. 기본값은 5000.

공유 COPY 옵션

COPY TO와 COPY FROM 모두에 공통인 옵션.

NULLVAL null 값의 문자열 자리 표시자. 기본값은 null.

HEADER COPY TO의 경우 CSV 출력 파일의 첫 줄에 컬럼 이름이 포함될지 제어합니다. COPY FROM의 경우 CSV 입력 파일의 첫 줄에 컬럼 이름이 포함되는지 지정합니다. 기본값은 false.

DECIMALSEP 소수점 구분자로 사용되는 문자. 기본값은 ..

THOUSANDSSEP 천 단위 구분에 사용되는 문자. 기본값은 빈 문자열.

BOOLSTYLE 불리언 값의 문자열 리터럴 형식. 기본값은 True,False.

NUMPROCESSES COPY 작업을 위해 생성할 자식 워커 프로세스 수. COPY 작업의 기본값은 16. 다만 기껏해야 (num_cores - 1) 프로세스가 생성됩니다.

MAXATTEMPTS 포기하기 전에 데이터 범위를 가져오거나(COPY TO 사용 시) 데이터 청크를 삽입하는(COPY FROM 사용 시) 실패 시도의 최대 횟수. 기본값은 5.

REPORTFREQUENCY 상태 업데이트가 새로고침되는 빈도(초). 기본값은 0.25.

RATEFILE 속도 통계를 출력할 선택적 파일. 기본적으로 통계는 파일로 출력되지 않습니다.

따옴표 이스케이프

날짜, IP 주소, 문자열은 작은따옴표로 감싸야 합니다. 문자열 리터럴에서 작은따옴표 자체를 사용하려면 작은따옴표로 이스케이프하세요.

단순 텍스트 데이터를 가져올 때 cqlsh는 따옴표 없이 문자열을 반환합니다. 하지만 복잡한 타입(컬렉션, 사용자 정의 타입 등)에서 텍스트 데이터를 가져올 때 cqlsh는 이스케이프된 문자를 포함한 따옴표 문자열을 반환합니다. 예를 들어:

단순 데이터

cqlsh> CREATE TABLE test.simple_data (id int, data text, PRIMARY KEY (id));
cqlsh> INSERT INTO test.simple_data (id, data) values(1, 'I''m fine');
cqlsh> SELECT data from test.simple_data; data
----------
 I'm fine

복잡한 데이터

cqlsh> CREATE TABLE test.complex_data (id int, data map<int, text>, PRIMARY KEY (id));
cqlsh> INSERT INTO test.complex_data (id, data) values(1, {1:'I''m fine'});
cqlsh> SELECT data from test.complex_data; data
------------------
 {1: 'I''m fine'}

더 알아보기 (Learn more)

• cqlshrc / credentials 설정
• nodetool — Cassandra 관리 도구