내장 스칼라 SQL 함수

이 페이지에서는 SQLite가 기본으로 제공하는 내장 스칼라 SQL 함수들에 대해 설명합니다. 각 함수의 이름, 인자, 반환 값, 그리고 사용 예시를 확인할 수 있어요.

출처: 문서

본문

1. 개요

기본적으로 아래 핵심 함수들을 사용할 수 있어요. 날짜 및 시간 함수, 집계 함수, 창 함수, 수학 함수, JSON 함수는 별도 문서에서 다루고 있어요. 애플리케이션은 sqlite3_create_function() API를 사용하여 C로 작성된 추가 함수를 정의해 데이터베이스 엔진에 추가할 수도 있어요.

simple-function-invocation:

simple-func ( expr ) , *

simple-func는 함수 이름, expr은 인자 표현식이에요. 즉, 함수명(인자, ...) 형태의 호출을 나타내요.

SQL 함수 호출이 SQL 표현식 맥락에서 어떻게 사용되는지 더 자세한 내용은 표현식 내 함수(functions within expressions) 문서를 참조하세요.

2. 핵심 함수 목록

abs(X)
changes()
char(X1,X2,...,XN)
coalesce(X,Y,...)
concat(X,...)
concat_ws(SEP,X,...)
format(FORMAT,...)
glob(X,Y)
hex(X)
if(B1,V1,...)
ifnull(X,Y)
iif(B1,V1,...)
instr(X,Y)
last_insert_rowid()
length(X)
like(X,Y)
like(X,Y,Z)
likelihood(X,Y)
likely(X)
load_extension(X)
load_extension(X,Y)
lower(X)
ltrim(X)
ltrim(X,Y)
max(X,Y,...)
min(X,Y,...)
nullif(X,Y)
octet_length(X)
printf(FORMAT,...)
quote(X)
random()
randomblob(N)
replace(X,Y,Z)
round(X)
round(X,Y)
rtrim(X)
rtrim(X,Y)
sign(X)
soundex(X)
sqlite_compileoption_get(N)
sqlite_compileoption_used(X)
sqlite_offset(X)
sqlite_source_id()
sqlite_version()
substr(X,Y)
substr(X,Y,Z)
substring(X,Y)
substring(X,Y,Z)
total_changes()
trim(X)
trim(X,Y)
typeof(X)
unhex(X)
unhex(X,Y)
unicode(X)
unistr(X)
unistr_quote(X)
unlikely(X)
upper(X)
zeroblob(N)

3. 내장 스칼라 SQL 함수 설명

abs(X)

abs(X) 함수는 숫자 인수 X의 절댓값을 반환해요. X가 NULL이면 abs(X)는 NULL을 반환해요. X가 숫자로 변환할 수 없는 문자열이나 BLOB이면 abs(X)는 0.0을 반환해요. X가 정수 -9223372036854775808이면 abs(X)는 정수 오버플로 오류를 발생시켜요. 그에 해당하는 양의 64비트 2의 보수 값이 없기 때문이에요.

changes()

changes() 함수는 가장 최근에 완료된 INSERT, DELETE 또는 UPDATE 문에 의해 변경, 삽입 또는 삭제된 데이터베이스 행 수를 반환해요. 하위 레벨 트리거 내의 문은 제외해요. changes() SQL 함수는 sqlite3_changes64() C/C++ 함수의 래퍼라서 변경 횟수를 세는 규칙도 동일하게 따라요.

char(X1,X2,...,XN)

char(X1,X2,...,XN) 함수는 각각 정수 X1부터 XN의 유니코드 코드 포인트 값을 갖는 문자들로 구성된 문자열을 반환해요.

coalesce(X,Y,...)

coalesce() 함수는 첫 번째 NULL이 아닌 인수의 복사본을 반환하고, 모든 인수가 NULL이면 NULL을 반환해요. coalesce()는 최소 2개의 인수가 필요해요.

concat(X,...)

concat(...) 함수는 NULL이 아닌 모든 인수의 문자열 표현을 이어붙인 문자열을 반환해요. 모든 인수가 NULL이면 concat()은 빈 문자열을 반환해요.

concat_ws(SEP,X,...)

concat_ws(SEP,...) 함수는 첫 번째 인수를 제외한 나머지 NULL이 아닌 인수들을 첫 번째 인수의 텍스트 값을 구분 기호로 사용해 이어붙인 문자열을 반환해요. 첫 번째 인수가 NULL이면 concat_ws()는 NULL을 반환해요. 첫 번째를 제외한 모든 인수가 NULL이면 concat_ws()는 빈 문자열을 반환해요.

format(FORMAT,...)

format(FORMAT,...) SQL 함수는 C 언어 함수인 sqlite3_mprintf() 및 표준 C 라이브러리의 printf() 함수처럼 동작해요. 첫 번째 인수는 이후 인수들의 값을 사용해 출력 문자열을 어떻게 구성할지 지정하는 형식 문자열이에요. FORMAT 인수가 없거나 NULL이면 결과는 NULL이에요. %n 형식은 조용히 무시되며 인수를 소비하지 않아요. %p 형식은 %X의 별칭이에요. %z 형식은 %s와 서로 바꿔 쓸 수 있어요. 인수 목록에 인수가 너무 적으면 누락된 인수는 NULL 값으로 간주하며, 숫자 형식에서는 0 또는 0.0으로, %s에서는 빈 문자열로 변환해요. 추가 정보는 내장 printf() 문서를 참조하세요.

glob(X,Y)

glob(X,Y) 함수는 "Y GLOB X" 표현식과 동일해요. glob() 함수에서 X와 Y 인수는 중위 GLOB 연산자와는 반대 순서라는 점에 유의하세요. Y는 문자열이고 X는 패턴이에요. 예를 들어 다음 표현식들은 동일해요:

     name GLOB '*helium*'
     glob('*helium*',name)

sqlite3_create_function() 인터페이스를 사용해 glob(X,Y) 함수를 다른 구현으로 재정의하면 GLOB 연산자는 그 대체 구현을 호출해요.

hex(X)

hex() 함수는 인수를 BLOB로 해석하고 해당 BLOB 내용의 대문자 16진수 표기 문자열을 반환해요.

"hex(X)"에서 인수 X가 정수나 부동 소수점 숫자라면, "인수를 BLOB로 해석한다"는 것은 먼저 이진 숫자가 UTF8 텍스트 표현으로 변환된 다음 그 텍스트가 BLOB로 해석된다는 뜻이에요. 따라서 "hex(12345678)"은 정수 값의 이진 표현인 "0000000000BC614E"가 아니라 "3132333435363738"로 표시돼요.

참고: unhex()

ifnull(X,Y)

ifnull() 함수는 첫 번째 NULL이 아닌 인수의 복사본을 반환하고, 두 인수가 모두 NULL이면 NULL을 반환해요. ifnull()은 정확히 2개의 인수가 필요해요. ifnull() 함수는 인수가 두 개인 coalesce()와 동일해요.

iif(B1,V1,...) if(B1,V1,...)

iif(B1,V1,...,BN,VN) 함수는 인수를 쌍으로 받아요. 각 쌍의 첫 번째 인수는 불리언이고, 두 번째 인수는 그 불리언이 참일 때 반환할 값이에요. iif() 함수는 첫 번째로 참이 되는 불리언에 연결된 값을 반환해요. iif()에 전달된 인수 개수가 홀수라면, 마지막 인수는 앞선 모든 불리언 인수가 거짓일 때 반환되는 값이에요. 인수 개수가 짝수이고 모든 불리언 인수가 거짓이면 NULL을 반환해요. iif() 함수는 최소 두 개의 인수가 필요해요. iif() 함수는 사실상 CASE 표현식의 간단한 표기법이에요. 예를 들어, iif(X,Y,Z) 함수는 "CASE WHEN X THEN Y ELSE Z END" CASE 표현식과 논리적으로 동일하고 동일한 바이트코드를 생성해요. if() 함수는 iif()의 대체 표기일 뿐이에요.

iif() 함수는 단락 평가(short-circuit evaluation)를 사용해요. 인수는 최종 결과를 계산하는 데 필요한 경우에만 평가돼요. 예를 들어 값 인수 중 하나가 값비싼 계산(정교한 서브쿼리 등)을 수반하지만 해당 불리언이 거짓이라면, 그 값비싼 계산은 결코 수행되지 않아요. 마찬가지로 첫 번째로 참이 되는 불리언 이후의 불리언 인수는 결코 평가되지 않아요.

iif() 함수는 원래 정확히 세 개의 인수가 필요했어요. 두 인수 버전의 iif()와 함수 이름을 "if()"로 쓸 수 있는 기능은 SQLite 버전 3.48.0(2025-01-14)에서 추가됐어요. 3개를 초과하는 인수를 받을 수 있는 기능은 SQLite 버전 3.49.0(2025-02-06)에서 추가됐어요.

instr(X,Y)

instr(X,Y) 함수는 문자열 X 안에서 문자열 Y가 처음 나타나는 위치를 찾아 그 앞의 문자 수에 1을 더한 값을 반환해요. Y가 X 안에서 전혀 발견되지 않으면 0을 반환해요. 또는 X와 Y가 모두 BLOB이라면 instr(X,Y)는 Y가 처음 나타나기 전의 바이트 수보다 1 큰 값을 반환하고, Y가 X 안에 전혀 없으면 0을 반환해요. instr(X,Y)의 두 인수 X와 Y가 모두 NULL이 아니면서 BLOB이 아니면 둘 다 문자열로 해석해요. instr(X,Y)에서 X나 Y 중 하나라도 NULL이면 결과는 NULL이에요.

last_insert_rowid()

last_insert_rowid() 함수는 해당 함수를 호출한 데이터베이스 연결에서 마지막으로 삽입된 행의 ROWID를 반환해요. last_insert_rowid() SQL 함수는 sqlite3_last_insert_rowid() C/C++ 인터페이스 함수의 래퍼예요.

length(X)

문자열 값 X에 대해 length(X) 함수는 첫 번째 U+0000 문자 앞에 있는 입력 문자열 X의 유니코드 코드 포인트 수(바이트 아님)를 반환해요. SQLite 문자열은 일반적으로 NUL 문자를 포함하지 않으므로 length(X) 함수는 보통 문자열 X의 전체 문자 수를 반환해요. BLOB 값 X에 대해 length(X)는 BLOB의 바이트 수를 반환해요. X가 NULL이면 length(X)는 NULL이에요. X가 숫자이면 length(X)는 X의 문자열 표현 길이를 반환해요.

문자열의 경우 length(X) 함수는 바이트 길이가 아니라 문자열의 문자(character) 또는 코드 포인트 길이를 반환한다는 점에 유의하세요. 문자 길이는 문자열에 있는 문자 수예요. UTF-16 문자열에서 문자 길이는 항상 바이트 길이와 달라요. UTF-8 문자열에서도 문자열에 멀티바이트 문자가 포함되어 있으면 바이트 길이와 다를 수 있어요. 문자열의 바이트 길이를 확인하려면 octet_length() 함수를 사용하세요.

BLOB 값의 경우 length(X)는 항상 BLOB의 바이트 길이를 반환해요.

문자열 값의 경우 length(X)는 문자 길이를 계산하기 위해 전체 문자열을 메모리로 읽어야 해요. 하지만 BLOB 값의 경우 SQLite는 이미 BLOB의 바이트 수를 알고 있으므로 전체 문자열을 메모리로 읽을 필요가 없어요. 따라서 수 메가바이트 크기의 값에서 length(X) 함수는 값을 메모리에 로드할 필요가 없기 때문에 보통 BLOB에 대해 문자열보다 훨씬 빨라요.

like(X,Y) like(X,Y,Z)

like() 함수는 "Y LIKE X [ESCAPE Z]" 표현식을 구현하는 데 사용돼요. 선택적 ESCAPE 절이 있으면 like() 함수는 세 개의 인수로 호출돼요. 그렇지 않으면 두 개의 인수로만 호출돼요. like() 함수에서 X와 Y 매개변수는 중위 LIKE 연산자와는 반대 순서라는 점에 유의하세요. X는 패턴이고 Y는 그 패턴에 매칭할 문자열이에요. 따라서 다음 표현식들은 동일해요:

     name LIKE '%neon%'
     like('%neon%',name)

sqlite3_create_function() 인터페이스를 사용해 like() 함수를 재정의하면 LIKE 연산자의 동작을 바꿀 수 있어요. like() 함수를 재정의할 때는 두 인수 버전과 세 인수 버전을 모두 재정의하는 것이 중요할 수 있어요. 그렇지 않으면 ESCAPE 절 지정 여부에 따라 LIKE 연산자를 구현하는 코드가 달라질 수 있어요.

likelihood(X,Y)

likelihood(X,Y) 함수는 인수 X를 변경하지 않고 그대로 반환해요. likelihood(X,Y)에서 값 Y는 0.0과 1.0 사이(경계 포함)의 부동 소수점 상수여야 해요. likelihood(X,Y) 함수는 코드 생성기가 최적화로 제거하는 no-op 함수라서 런타임(즉, sqlite3_step() 호출 중)에 CPU 사이클을 소비하지 않아요. likelihood(X,Y) 함수의 목적은 인수 X가 대략 Y의 확률로 참인 불리언이라는 힌트를 쿼리 플래너에 제공하는 거예요. unlikely(X) 함수는 likelihood(X,0.0625)의 줄임 표현이고, likely(X) 함수는 likelihood(X,0.9375)의 줄임 표현이에요.

likely(X)

likely(X) 함수는 인수 X를 변경하지 않고 그대로 반환해요. likely(X) 함수는 코드 생성기가 최적화로 제거하는 no-op 함수라서 런타임(즉, sqlite3_step() 호출 중)에 CPU 사이클을 소비하지 않아요. likely(X) 함수의 목적은 인수 X가 보통 참인 불리언 값이라는 힌트를 쿼리 플래너에 제공하는 거예요. likely(X) 함수는 likelihood(X,0.9375)와 동일해요. 참고: unlikely(X).

load_extension(X) load_extension(X,Y)

load_extension(X,Y) 함수는 엔트리 포인트 Y를 사용하여 이름이 X인 공유 라이브러리 파일에서 SQLite 확장을 로드해요. load_extension()의 결과는 항상 NULL이에요. Y가 생략되면 기본 엔트리 포인트 이름이 사용돼요. load_extension() 함수는 확장이 올바르게 로드되거나 초기화되지 못하면 예외를 발생시켜요.

확장이 SQL 함수나 정렬 순서(collating sequence)를 수정하거나 삭제하려고 하면 load_extension() 함수는 실패해요. 확장은 새 함수나 정렬 순서를 추가할 수 있지만, 기존 함수나 정렬 순서를 수정하거나 삭제할 수는 없어요. 그 함수나 정렬 순서가 현재 실행 중인 SQL 문의 다른 곳에서 사용될 수 있기 때문이에요. 함수나 정렬 순서를 변경하거나 삭제하는 확장을 로드하려면 sqlite3_load_extension() C 언어 API를 사용하세요.

보안상의 이유로 확장 로딩은 기본적으로 비활성화되어 있으며, sqlite3_enable_load_extension()을 먼저 호출해 활성화해야 해요.

lower(X)

lower(X) 함수는 모든 ASCII 문자를 소문자로 변환한 문자열 X의 복사본을 반환해요. 기본 내장 lower() 함수는 ASCII 문자에 대해서만 동작해요. 비-ASCII 문자에 대해 대소문자 변환을 하려면 ICU 확장을 로드하세요.

ltrim(X) ltrim(X,Y)

ltrim(X,Y) 함수는 X의 왼쪽에서 Y에 나타나는 모든 문자를 제거해 형성된 문자열을 반환해요. Y 인수가 생략되면 ltrim(X)은 X의 왼쪽에서

내장 스칼라 SQL 함수