쿼리 실행

참고 항목

이 콘텐츠는 CodeQL CLI의 최신 릴리스에 대해 설명합니다. 이 요소에 대한 자세한 내용은 http://github.com/github/codeql-cli-binaries/releases을(를) 참조하세요.

이전 릴리스에서 이 명령에 사용할 수 있는 옵션의 세부 정보를 보려면 터미널에서 옵션을 사용하여 --help 명령을 실행합니다.

개요

Shell

codeql execute queries [--output=<dir|file.bqrs>] [--threads=<num>] <options>... -- <dataset> <query|dir|suite|pack>...

codeql execute queries [--output=<dir|file.bqrs>] [--threads=<num>] <options>... -- <dataset> <query|dir|suite|pack>...

Description

          \[내부 처리] 데이터 세트에 대해 하나 이상의 쿼리를 실행합니다.

이 명령은 일반적으로 직접 호출하면 안 됩니다. 대신 codeql database run-queries 또는 codeql query run을 사용하세요. 이렇게 하면 QL 평가기의 성능을 조정하기 위한 특정 JVM 옵션과 함께 codeql execute queries가 시작됩니다.

Options

기본 옵션

`<dataset>`

          \[필수] 쿼리할 원시 QL 데이터 세트의 경로입니다.

`<query|dir|suite|pack>...`

          \[필수] 실행할 쿼리입니다. 각 인수는 `scope/name@range:path` 형식이며, 여기서 다음을 의미합니다.

          `scope/name`은(는) CodeQL 팩의 정규화된 이름입니다.

          `range`은(는) semver 범위입니다.

          `path`은(는) 파일 시스템 경로입니다.

scope/name을(를) 지정하면 range 및 path은(는) 선택 사항입니다. range이(가) 누락되면 지정된 팩의 최신 버전을 의미합니다. path이(가) 누락되면 지정된 팩의 기본 쿼리 도구 모음을 의미합니다.

path은(는) *.ql 쿼리 파일, 하나 이상의 쿼리를 포함하는 디렉터리, 또는 .qls 쿼리 도구 모음 파일 중 하나일 수 있습니다. 팩 이름을 지정하지 않은 경우 path을(를) 제공해야 하며, 현재 프로세스의 작업 디렉터리를 기준으로 해석됩니다.

리터럴 @ 또는 :을(를) 포함하는 path을(를) 지정하려면 인수 앞에 path:을(를) 접두사로 사용하세요. 예: path:directory/with:and@/chars.

scope/name 및 path을(를) 지정한 경우 path은(는) 절대 경로일 수 없습니다. 이는 CodeQL 팩의 루트를 기준으로 하는 상대 경로로 간주됩니다.

`-o, --output=<dir|file.bqrs>`

보통 이는 쿼리의 BQRS 출력이 기록될 기존 디렉터리입니다. 이 디렉터리 내의 파일 이름은 QL 파일 이름에서 파생됩니다.

또는 실행할 쿼리가 정확히 하나라면, 기록할 실제 BQRS 파일의 이름일 수도 있고, 결과의 사람이 읽을 수 있는 표현을 표준 출력으로 쓰기 위해 생략할 수도 있습니다.

`--no-rerun`

출력 위치에 이미 BQRS 결과가 저장되어 있는 것으로 보이는 쿼리는 평가를 생략합니다.

사용할 모델 팩을 제어하는 옵션

          `--model-packs=<`
          <name@range>>...

각각 선택적인 버전 범위를 포함하는 CodeQL 팩 이름 목록으로, 평가할 쿼리를 사용자 지정하기 위한 모델 팩으로 사용됩니다.

사용할 위협 모델을 제어하는 옵션

`--threat-model=<name>...`

활성화 또는 비활성화할 위협 모델 목록입니다.

인수는 위협 모델의 이름이며, 선택적으로 앞에 '!'를 붙일 수 있습니다. '!'가 없으면, 지정된 위협 모델과 그 모든 하위 항목이 활성화됩니다. '!'가 있으면, 지정된 위협 모델과 그 모든 하위 항목이 비활성화됩니다.

'기본' 위협 모델은 기본적으로 활성화되어 있지만, '--threat-model !default'를 지정하여 비활성화할 수 있습니다.

'전체' 위협 모델은 모든 위협 모델을 활성화하거나 비활성화하는 데 사용할 수 있습니다.

--threat-model 옵션은 순서대로 처리됩니다. 예를 들어 '--threat-model local --threat-model !environment'는 '환경' 위협 모델을 제외한 '로컬' 그룹의 모든 위협 모델을 활성화합니다.

이 옵션은 위협 모델을 지원하는 언어에만 영향을 미칩니다.

v2.15.3부터 사용할 수 있습니다.

쿼리 평가기를 제어하는 옵션

`--[no-]tuple-counting`

          \[고급] 쿼리 평가기 로그에서 각 평가 단계의 튜플 수를 표시합니다. `--evaluator-log` 옵션이 제공되면, 튜플 수가 명령에서 생성되는 텍스트 기반 로그와 구조화된 JSON 로그 모두에 포함됩니다. (이는 복잡한 QL 코드의 성능 최적화에 유용할 수 있습니다.)

`--timeout=<seconds>`

          \[고급] 쿼리 평가의 시간 제한 길이를 초 단위로 설정합니다.

시간 제한 기능은 복잡한 쿼리를 평가하는 데 시간이 “무한정” 걸릴 수 있는 경우를 포착하기 위한 것입니다. 이는 쿼리 평가가 걸릴 수 있는 총 시간을 제한하는 효과적인 방법이 아닙니다. 평가는 계산의 각 개별 타이밍 구간이 시간 제한 내에 완료되는 한 계속 진행됩니다. 현재 이러한 개별 타이밍 구간은 최적화된 쿼리의 “RA 계층”이지만, 향후 변경될 수 있습니다.

시간 제한을 지정하지 않거나 0으로 지정하면 시간 제한이 설정되지 않습니다(codeql test run은(는) 예외이며, 기본 시간 제한은 5분입니다).

`-j, --threads=<num>`

쿼리를 평가하는 데 사용할 스레드 수입니다.

기본값은 1입니다. 0을 전달하면 머신의 코어당 스레드 1개를 사용하며, -_N_을 전달하면 _N_개 코어를 사용하지 않게 됩니다(단, 최소 1개 스레드는 여전히 사용합니다).

`--[no-]save-cache`

          \[사용되지 않음] \[고급] 이 플래그는 아무 작업도 수행하지 않습니다.

`--[no-]expect-discarded-cache`

          \[고급] 쿼리가 실행된 후 캐시가 폐기될 것이라는 가정 하에, 어떤 조건자를 평가할지와 디스크 캐시에 무엇을 쓸지 결정합니다.

`--[no-]keep-full-cache`

          \[고급] 평가가 완료된 후 디스크 캐시를 정리하지 않습니다.

이는 이후에 codeql dataset cleanup 또는 codeql database cleanup을 수행할 예정이라면 시간을 절약할 수 있습니다.

`--max-disk-cache=<MB>`

중간 쿼리 결과에 대한 디스크 캐시가 사용할 수 있는 최대 공간을 설정합니다.

이 크기를 명시적으로 구성하지 않으면, 평가는 데이터 세트의 크기와 쿼리의 복잡도를 기준으로 “합리적인” 양의 캐시 공간을 사용하려고 시도합니다. 이 기본 사용량보다 높은 한도를 명시적으로 설정하면 추가 캐시가 활성화되어 이후 쿼리를 더 빠르게 실행할 수 있습니다.

`--min-disk-free=<MB>`

          \[고급] 파일 시스템의 목표 여유 공간 양을 설정합니다.

--max-disk-cache이(가) 제공되지 않으면, 평가기는 파일 시스템의 여유 공간이 이 값 아래로 떨어질 경우 디스크 캐시 사용량을 최대한 줄이려고 합니다.

`--min-disk-free-pct=<pct>`

          \[고급] 파일 시스템의 목표 여유 공간 비율을 설정합니다.

--max-disk-cache이(가) 제공되지 않으면, 평가기는 파일 시스템의 여유 공간이 이 비율 아래로 떨어질 경우 디스크 캐시 사용량을 최대한 줄이려고 합니다.

`--external=<pred>=<file.csv>`

외부 조건자 <pred> 에 대한 행을 포함하는 CSV 파일입니다. 여러 개의 --external 옵션을 제공할 수 있습니다.

`--xterm-progress=<mode>`

          \[고급] xterm 제어 시퀀스를 사용하여 QL 평가 중 진행 상황 추적을 표시할지 여부를 제어합니다. 가능한 값은 다음과 같습니다.

          `no`: 복잡한 진행 표시는 절대 생성하지 않으며, 단순 터미널이라고 가정합니다.

          `auto`              _(기본값)_: 명령이 적절한 터미널에서 실행 중인지 자동으로 감지합니다.

          `yes`: 터미널이 xterm 제어 시퀀스를 이해할 수 있다고 가정합니다. 이 기능은 터미널의 _크기_를 자동 감지할 수 있어야 하는데(Windows에서는 구현되어 있지 않습니다), `-q`이(가) 제공되면 비활성화됩니다.

          `25x80` (또는 이와 유사): `yes`와(과) 같지만, 터미널의 크기도 명시적으로 제공합니다. (`yes`과(와) 달리, 이 옵션은 Windows에서 작동해야 합니다.)

          `25x80:/dev/pts/17` (또는 유사한 값): stderr와 _다른_ 터미널에서 복잡한 진행 표시를 보여줍니다. 주로 내부 테스트에 유용합니다.

구조화된 평가기 로그 출력 제어 옵션

`--evaluator-log=<file>`

          \[고급] 평가기 성능에 대한 구조화된 로그를 지정된 파일로 출력합니다. 이 로그 파일의 형식은 예고 없이 변경될 수 있지만, 기본적으로는 두 개의 줄바꿈 문자로 구분된 JSON 객체 스트림이며, `--evaluator-log-minify` 옵션이 전달되면 하나의 줄바꿈 문자로 구분됩니다. 이 파일의 더 안정적인 요약을 생성하려면 `codeql generate log-summary <file>`을(를) 사용하고, 파일을 직접 파싱하는 것은 피하세요. 파일이 이미 존재하면 덮어씁니다.

`--evaluator-log-minify`

          \[고급] `--evaluator-log` 옵션이 전달된 경우, 이 옵션도 함께 전달하면 JSON 로그 크기가 줄어드는 대신 사람이 읽기 훨씬 어려워집니다.

QL 컴파일 제어 옵션

`--warnings=<mode>`

QL 컴파일러의 경고를 처리하는 방법입니다. 다음 중 하나입니다.

          `hide`: 경고를 억제합니다.

          `show`              _(기본값)_: 경고를 출력하되 컴파일을 계속합니다.

          `error`: 경고를 오류로 처리합니다.

`--no-debug-info`

디버깅을 위해 RA에서 소스 위치 정보를 내보내지 않습니다.

`--[no-]fast-compilation`

          \[사용 중단됨] \[고급] 특히 느린 최적화 단계를 생략합니다.

`--no-release-compatibility`

          \[고급] 이식성을 희생하고 최신 컴파일러 기능을 사용합니다.

때때로 새로운 QL 언어 기능과 평가기 최적화는, QL 컴파일러에서 기본으로 활성화되기 몇 릴리스 전부터 QL 평가기에서 지원됩니다. 이렇게 하면 최신 CodeQL 릴리스에서 쿼리를 개발할 때의 성능을, 코드 검사 또는 CI 통합에서 아직 사용 중일 수 있는 약간 더 오래된 릴리스에서도 맞출 수 있습니다.

쿼리가 다른(이전 또는 이후) CodeQL 릴리스와 호환되는지에 신경 쓰지 않는다면, 이 플래그를 사용하여 컴파일러의 최근 개선 사항을 조기에 활성화함으로써 때때로 약간의 추가 성능을 얻을 수 있습니다.

활성화할 최근 개선 사항이 없는 릴리스에서는 이 옵션이 조용히 아무 작업도 하지 않습니다. 따라서 전역 CodeQL 구성 파일에 한 번 설정해 두어도 안전합니다.

v2.11.1부터 사용할 수 있습니다.

`--[no-]local-checking`

사용되는 QL 소스 부분에 대해서만 초기 검사를 수행합니다.

`--no-metadata-verification`

QLDoc 주석에 포함된 쿼리 메타데이터의 유효성을 검사하지 않습니다.

`--compilation-cache-size=<MB>`

          \[고급] 컴파일 캐시 디렉터리의 기본 최대 크기를 재정의합니다.

`--fail-on-ambiguous-relation-name`

          \[고급] 컴파일 중에 모호한 관계 이름이 생성되면 컴파일을 실패 처리합니다.

컴파일 환경 설정 옵션

`--search-path=<dir>[:<dir>...]`

QL 팩이 존재할 수 있는 디렉터리 목록입니다. 각 디렉터리는 QL 팩(또는 루트에 .codeqlmanifest.json 파일이 있는 팩 번들)일 수도 있고, 그러한 디렉터리 하나 이상을 포함하는 바로 위의 부모 디렉터리일 수도 있습니다.

경로에 디렉터리가 둘 이상 포함되면, 그 순서가 우선 순위를 정의합니다. 해결해야 하는 팩 이름이 둘 이상의 디렉터리 트리에서 일치하면, 먼저 지정된 디렉터리가 승리합니다.

오픈 소스 CodeQL 리포지토리의 체크아웃을 가리키도록 하면, 그 안에 있는 언어 중 하나를 쿼리할 때 작동해야 합니다.

압축 해제된 CodeQL 툴체인과 형제 위치에 CodeQL 리포지토리를 체크아웃한 경우 이 옵션을 지정할 필요가 없으며, 이런 형제 디렉터리는 다른 방법으로 찾을 수 없는 QL 팩을 찾기 위해 항상 검색됩니다. (이 기본값이 작동하지 않으면, 사용자별 구성 파일에서 --search-path을(를) 한 번 설정해 두는 것을 강력히 권장합니다.)

(참고: Windows에서 경로 구분자는 ;입니다.)

`--additional-packs=<dir>[:<dir>...]`

이 디렉터리 목록이 제공되면, --search-path에 있는 디렉터리보다 먼저 팩을 검색합니다. 이들 간의 순서는 중요하지 않습니다. 이 목록을 통해 두 곳에서 동일한 팩 이름이 발견되면 오류입니다.

이는 기본 경로에도 존재하는 팩의 새 버전을 임시로 개발할 때 유용합니다. 반면 구성 파일에서 이 옵션을 재정의하는 것은 권장되지 않습니다. 일부 내부 작업이 즉석에서 이 옵션을 추가하여 구성된 값을 덮어씁니다.

(참고: Windows에서 경로 구분자는 ;입니다.)

`--library-path=<dir>[:<dir>...]`

          \[고급] QL 라이브러리의 원시 가져오기 검색 경로에 추가될 선택적 디렉터리 목록입니다. 이는 QL 팩으로 패키징되지 않은 QL 라이브러리를 사용하는 경우에만 사용해야 합니다.

(참고: Windows에서 경로 구분자는 ;입니다.)

`--dbscheme=<file>`

          \[고급] 어떤 dbscheme 쿼리를 대상으로 컴파일해야 하는지 명시적으로 정의합니다. 이는 자신이 무엇을 하는지 완전히 확신하는 호출자만 제공해야 합니다.

`--compilation-cache=<dir>`

          \[고급] 컴파일 캐시로 사용할 추가 디렉터리를 지정합니다.

`--no-default-compilation-cache`

          \[고급] 쿼리가 포함된 QL 팩이나 CodeQL 툴체인 디렉터리 등 표준 위치의 컴파일 캐시를 사용하지 않습니다.

CodeQL 패키지 관리자 구성 옵션

`--registries-auth-stdin`

쉼표로 구분된 <registry_url>=<token> 쌍 목록을 전달하여 GitHub Enterprise Server 컨테이너 레지스트리에 인증합니다.

예를 들어 http://containers.GHEHOSTNAME1/v2/=TOKEN1,http://containers.GHEHOSTNAME2/v2/=TOKEN2을(를) 전달하면 두 개의 GitHub Enterprise Server 인스턴스에 인증할 수 있습니다.

이는 CODEQL_REGISTRIES_AUTH 및 GITHUB_TOKEN 환경 변수를 재정의합니다. github.com Container 레지스트리에만 인증해야 하는 경우, 더 단순한 --github-auth-stdin 옵션을 사용하여 인증할 수 있습니다.

`--github-auth-stdin`

표준 입력을 통해 github.com GitHub 앱 토큰 또는 개인 액세스 토큰을 전달하여 github.com 컨테이너 레지스트리에 인증합니다.

GitHub Enterprise Server 컨테이너 레지스트리에 인증하려면 --registries-auth-stdin을(를) 전달하거나 CODEQL_REGISTRIES_AUTH 환경 변수를 사용하세요.

이는 GITHUB_TOKEN 환경 변수를 재정의합니다.

          \[고급] 명령을 실행하는 JVM에 옵션을 제공합니다.

(공백을 포함하는 옵션은 올바르게 처리되지 않을 수 있으므로 주의하세요.)

          \[고급] 상세 정보 표시 수준을 오류, 경고, 진행률, 진행률+, 진행률++, 진행률+++ 중 하나로 명시적으로 설정합니다. 
          `-v` 및 `-q`를 재정의합니다.

`--logdir=<dir>`

          \[고급] 지정된 디렉터리에 자세한 로그를 하나 이상의 파일로 기록하며, 생성된 이름에는 타임스탬프와 실행 중인 하위 명령 이름이 포함됩니다.

(로그 파일 이름을 완전히 제어하려면 대신 --log-to-stderr을(를) 제공하고 필요에 따라 stderr를 리디렉션하세요.)

`--common-caches=<dir>`

          \[고급] 다운로드한 QL 팩 및 컴파일된 쿼리 계획과 같이 CLI를 여러 번 실행하는 동안 유지되는 디스크의 캐시된 데이터 위치를 제어합니다. 명시적으로 설정하지 않으면 기본값은 사용자의 홈 디렉터리에 있는 `.codeql`(이)라는 이름의 디렉터리이며, 이미 존재하지 않으면 생성됩니다.

v2.15.2부터 사용할 수 있습니다.

누가 이 기능을 사용할 수 있나요?

이 문서의 내용