{"meta":{"title":"쿼리 실행","intro":"[내부 처리] 데이터 세트에 대해 하나 이상의 쿼리를 실행합니다.","product":"보안 및 코드 품질","breadcrumbs":[{"href":"/ko/code-security","title":"보안 및 코드 품질"},{"href":"/ko/code-security/reference","title":"Reference"},{"href":"/ko/code-security/reference/code-scanning","title":"코드 검사"},{"href":"/ko/code-security/reference/code-scanning/codeql","title":"CodeQL"},{"href":"/ko/code-security/reference/code-scanning/codeql/codeql-cli-manual","title":"CodeQL CLI 매뉴얼"},{"href":"/ko/code-security/reference/code-scanning/codeql/codeql-cli-manual/execute-queries","title":"쿼리 실행"}],"documentType":"article"},"body":"# 쿼리 실행\n\n\\[내부 처리] 데이터 세트에 대해 하나 이상의 쿼리를 실행합니다.\n\n> \\[!NOTE]\n> 이 콘텐츠는 CodeQL CLI의 최신 릴리스에 대해 설명합니다. 이 요소에 대한 자세한 내용은 <https://github.com/github/codeql-cli-binaries/releases을(를)> 참조하세요.\n>\n> 이전 릴리스에서 이 명령에 사용할 수 있는 옵션의 세부 정보를 보려면 터미널에서 옵션을 사용하여 <span style=\"white-space: nowrap;\">`--help`</span> 명령을 실행합니다.\n\n## 개요\n\n```shell copy\ncodeql execute queries [--output=<dir|file.bqrs>] [--threads=<num>] <options>... -- <dataset> <query|dir|suite|pack>...\n```\n\n## Description\n\n```\n          \\[내부 처리] 데이터 세트에 대해 하나 이상의 쿼리를 실행합니다.\n```\n\n이 명령은 일반적으로 직접 호출하면 안 됩니다. 대신 [codeql database run-queries](/ko/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-run-queries) 또는 [codeql query run](/ko/code-security/reference/code-scanning/codeql/codeql-cli-manual/query-run)을 사용하세요. 이렇게 하면 QL 평가기의 성능을 조정하기 위한 특정 JVM 옵션과 함께 codeql execute queries가 시작됩니다.\n\n## Options\n\n### 기본 옵션\n\n#### `<dataset>`\n\n```\n          \\[필수] 쿼리할 원시 QL 데이터 세트의 경로입니다.\n```\n\n#### `<query|dir|suite|pack>...`\n\n```\n          \\[필수] 실행할 쿼리입니다. 각 인수는 `scope/name@range:path` 형식이며, 여기서 다음을 의미합니다.\n```\n\n* `scope/name`은(는) CodeQL 팩의 정규화된 이름입니다.\n* `range`은(는) semver 범위입니다.\n* `path`은(는) 파일 시스템 경로입니다.\n\n  ```\n          `scope/name`을(를) 지정하면 `range` 및 `path`은(는) 선택 사항입니다. \n          `range`이(가) 누락되면 지정된 팩의 최신 버전을 의미합니다. \n          `path`이(가) 누락되면 지정된 팩의 기본 쿼리 도구 모음을 의미합니다.\n\n          `path`은(는) `*.ql` 쿼리 파일, 하나 이상의 쿼리를 포함하는 디렉터리, 또는 `.qls` 쿼리 도구 모음 파일 중 하나일 수 있습니다. 팩 이름을 지정하지 않은 경우 `path`을(를) 제공해야 하며, 현재 프로세스의 작업 디렉터리를 기준으로 해석됩니다.\n  ```\n\n리터럴 `path` 또는 `@`을(를) 포함하는 `:`을(를) 지정하려면 인수 앞에 `path:`을(를) 접두사로 사용하세요. 예: `path:directory/with:and@/chars`.\n\n```\n          `scope/name` 및 `path`을(를) 지정한 경우 `path`은(는) 절대 경로일 수 없습니다. 이는 CodeQL 팩의 루트를 기준으로 하는 상대 경로로 간주됩니다.\n```\n\n#### `-o, --output=<dir|file.bqrs>`\n\n보통 이는 쿼리의 BQRS 출력이 기록될 기존 디렉터리입니다. 이 디렉터리 *내의* 파일 이름은 QL 파일 이름에서 파생됩니다.\n\n또는 실행할 쿼리가 정확히 하나라면, 기록할 실제 BQRS 파일의 이름일 수도 있고, 결과의 사람이 읽을 수 있는 표현을 표준 출력으로 쓰기 위해 생략할 수도 있습니다.\n\n#### `--no-rerun`\n\n출력 위치에 이미 BQRS 결과가 저장되어 있는 것으로 보이는 쿼리는 평가를 생략합니다.\n\n### 사용할 모델 팩을 제어하는 옵션\n\n####\n\n```\n          `--model-packs=<`\n          <name@range>>...\n```\n\n각각 선택적인 버전 범위를 포함하는 CodeQL 팩 이름 목록으로, 평가할 쿼리를 사용자 지정하기 위한 모델 팩으로 사용됩니다.\n\n### 사용할 위협 모델을 제어하는 옵션\n\n#### `--threat-model=<name>...`\n\n활성화 또는 비활성화할 위협 모델 목록입니다.\n\n인수는 위협 모델의 이름이며, 선택적으로 앞에 '!'를 붙일 수 있습니다. '!'가 없으면, 지정된 위협 모델과 그 모든 하위 항목이 활성화됩니다. '!'가 있으면, 지정된 위협 모델과 그 모든 하위 항목이 비활성화됩니다.\n\n'기본' 위협 모델은 기본적으로 활성화되어 있지만, '--threat-model !default'를 지정하여 비활성화할 수 있습니다.\n\n'전체' 위협 모델은 모든 위협 모델을 활성화하거나 비활성화하는 데 사용할 수 있습니다.\n\n\\--threat-model 옵션은 순서대로 처리됩니다. 예를 들어 '--threat-model local --threat-model !environment'는 '환경' 위협 모델을 제외한 '로컬' 그룹의 모든 위협 모델을 활성화합니다.\n\n이 옵션은 위협 모델을 지원하는 언어에만 영향을 미칩니다.\n\n```\n          `v2.15.3`부터 사용할 수 있습니다.\n```\n\n### 쿼리 평가기를 제어하는 옵션\n\n#### `--[no-]tuple-counting`\n\n```\n          \\[고급] 쿼리 평가기 로그에서 각 평가 단계의 튜플 수를 표시합니다. \n          `--evaluator-log` 옵션이 제공되면, 튜플 수가 명령에서 생성되는 텍스트 기반 로그와 구조화된 JSON 로그 모두에 포함됩니다. (이는 복잡한 QL 코드의 성능 최적화에 유용할 수 있습니다.)\n```\n\n#### `--timeout=<seconds>`\n\n```\n          \\[고급] 쿼리 평가의 시간 제한 길이를 초 단위로 설정합니다.\n```\n\n시간 제한 기능은 복잡한 쿼리를 평가하는 데 시간이 “무한정” 걸릴 수 있는 경우를 포착하기 위한 것입니다. 이는 쿼리 평가가 걸릴 수 있는 총 시간을 제한하는 효과적인 방법이 아닙니다. 평가는 계산의 각 개별 타이밍 구간이 시간 제한 내에 완료되는 한 계속 진행됩니다. 현재 이러한 개별 타이밍 구간은 최적화된 쿼리의 “RA 계층”이지만, 향후 변경될 수 있습니다.\n\n시간 제한을 지정하지 않거나 0으로 지정하면 시간 제한이 설정되지 않습니다([codeql test run](/ko/code-security/reference/code-scanning/codeql/codeql-cli-manual/test-run)은(는) 예외이며, 기본 시간 제한은 5분입니다).\n\n#### `-j, --threads=<num>`\n\n쿼리를 평가하는 데 사용할 스레드 수입니다.\n\n기본값은 1입니다. 0을 전달하면 머신의 코어당 스레드 1개를 사용하며, -\\_N\\_을 전달하면 \\_N\\_개 코어를 사용하지 않게 됩니다(단, 최소 1개 스레드는 여전히 사용합니다).\n\n#### `--[no-]save-cache`\n\n```\n          \\[사용되지 않음] \\[고급] 이 플래그는 아무 작업도 수행하지 않습니다.\n```\n\n#### `--[no-]expect-discarded-cache`\n\n```\n          \\[고급] 쿼리가 실행된 후 캐시가 폐기될 것이라는 가정 하에, 어떤 조건자를 평가할지와 디스크 캐시에 무엇을 쓸지 결정합니다.\n```\n\n#### `--[no-]keep-full-cache`\n\n```\n          \\[고급] 평가가 완료된 후 디스크 캐시를 정리하지 않습니다.\n```\n\n이는 이후에 [codeql dataset cleanup](/ko/code-security/reference/code-scanning/codeql/codeql-cli-manual/dataset-cleanup) 또는 [codeql database cleanup](/ko/code-security/reference/code-scanning/codeql/codeql-cli-manual/database-cleanup)을 수행할 예정이라면 시간을 절약할 수 있습니다.\n\n#### `--max-disk-cache=<MB>`\n\n중간 쿼리 결과에 대한 디스크 캐시가 사용할 수 있는 최대 공간을 설정합니다.\n\n이 크기를 명시적으로 구성하지 않으면, 평가는 데이터 세트의 크기와 쿼리의 복잡도를 기준으로 “합리적인” 양의 캐시 공간을 사용하려고 시도합니다. 이 기본 사용량보다 높은 한도를 명시적으로 설정하면 추가 캐시가 활성화되어 이후 쿼리를 더 빠르게 실행할 수 있습니다.\n\n#### `--min-disk-free=<MB>`\n\n```\n          \\[고급] 파일 시스템의 목표 여유 공간 양을 설정합니다.\n\n          `--max-disk-cache`이(가) 제공되지 않으면, 평가기는 파일 시스템의 여유 공간이 이 값 아래로 떨어질 경우 디스크 캐시 사용량을 최대한 줄이려고 합니다.\n```\n\n#### `--min-disk-free-pct=<pct>`\n\n```\n          \\[고급] 파일 시스템의 목표 여유 공간 비율을 설정합니다.\n\n          `--max-disk-cache`이(가) 제공되지 않으면, 평가기는 파일 시스템의 여유 공간이 이 비율 아래로 떨어질 경우 디스크 캐시 사용량을 최대한 줄이려고 합니다.\n```\n\n#### `--external=<pred>=<file.csv>`\n\n외부 조건자 *\\<pred>* 에 대한 행을 포함하는 CSV 파일입니다.\n여러 개의 `--external` 옵션을 제공할 수 있습니다.\n\n#### `--xterm-progress=<mode>`\n\n```\n          \\[고급] xterm 제어 시퀀스를 사용하여 QL 평가 중 진행 상황 추적을 표시할지 여부를 제어합니다. 가능한 값은 다음과 같습니다.\n\n          `no`: 복잡한 진행 표시는 절대 생성하지 않으며, 단순 터미널이라고 가정합니다.\n\n          `auto`\n          _(기본값)_: 명령이 적절한 터미널에서 실행 중인지 자동으로 감지합니다.\n\n          `yes`: 터미널이 xterm 제어 시퀀스를 이해할 수 있다고 가정합니다. 이 기능은 터미널의 _크기_를 자동 감지할 수 있어야 하는데(Windows에서는 구현되어 있지 않습니다), `-q`이(가) 제공되면 비활성화됩니다.\n\n          `25x80` (또는 이와 유사): `yes`와(과) 같지만, 터미널의 크기도 명시적으로 제공합니다. (`yes`과(와) 달리, 이 옵션은 Windows에서 작동해야 합니다.)\n\n          `25x80:/dev/pts/17` (또는 유사한 값): stderr와 _다른_ 터미널에서 복잡한 진행 표시를 보여줍니다. 주로 내부 테스트에 유용합니다.\n```\n\n### 구조화된 평가기 로그 출력 제어 옵션\n\n#### `--evaluator-log=<file>`\n\n```\n          \\[고급] 평가기 성능에 대한 구조화된 로그를 지정된 파일로 출력합니다. 이 로그 파일의 형식은 예고 없이 변경될 수 있지만, 기본적으로는 두 개의 줄바꿈 문자로 구분된 JSON 객체 스트림이며, `--evaluator-log-minify` 옵션이 전달되면 하나의 줄바꿈 문자로 구분됩니다. 이 파일의 더 안정적인 요약을 생성하려면 `codeql generate log-summary <file>`을(를) 사용하고, 파일을 직접 파싱하는 것은 피하세요. 파일이 이미 존재하면 덮어씁니다.\n```\n\n#### `--evaluator-log-minify`\n\n```\n          \\[고급] `--evaluator-log` 옵션이 전달된 경우, 이 옵션도 함께 전달하면 JSON 로그 크기가 줄어드는 대신 사람이 읽기 훨씬 어려워집니다.\n```\n\n### QL 컴파일 제어 옵션\n\n#### `--warnings=<mode>`\n\nQL 컴파일러의 경고를 처리하는 방법입니다. 다음 중 하나입니다.\n\n```\n          `hide`: 경고를 억제합니다.\n\n          `show`\n          _(기본값)_: 경고를 출력하되 컴파일을 계속합니다.\n\n          `error`: 경고를 오류로 처리합니다.\n```\n\n#### `--no-debug-info`\n\n디버깅을 위해 RA에서 소스 위치 정보를 내보내지 않습니다.\n\n#### `--[no-]fast-compilation`\n\n```\n          \\[사용 중단됨] \\[고급] 특히 느린 최적화 단계를 생략합니다.\n```\n\n#### `--no-release-compatibility`\n\n```\n          \\[고급] 이식성을 희생하고 최신 컴파일러 기능을 사용합니다.\n```\n\n때때로 새로운 QL 언어 기능과 평가기 최적화는, QL 컴파일러에서 기본으로 활성화되기 몇 릴리스 전부터 QL 평가기에서 지원됩니다. 이렇게 하면 최신 CodeQL 릴리스에서 쿼리를 개발할 때의 성능을, 코드 검사 또는 CI 통합에서 아직 사용 중일 수 있는 약간 더 오래된 릴리스에서도 맞출 수 있습니다.\n\n쿼리가 다른(이전 또는 이후) CodeQL 릴리스와 호환되는지에 신경 쓰지 않는다면, 이 플래그를 사용하여 컴파일러의 최근 개선 사항을 조기에 활성화함으로써 때때로 약간의 추가 성능을 얻을 수 있습니다.\n\n활성화할 최근 개선 사항이 없는 릴리스에서는 이 옵션이 조용히 아무 작업도 하지 않습니다. 따라서 전역 CodeQL 구성 파일에 한 번 설정해 두어도 안전합니다.\n\n```\n          `v2.11.1`부터 사용할 수 있습니다.\n```\n\n#### `--[no-]local-checking`\n\n사용되는 QL 소스 부분에 대해서만 초기 검사를 수행합니다.\n\n#### `--no-metadata-verification`\n\nQLDoc 주석에 포함된 쿼리 메타데이터의 유효성을 검사하지 않습니다.\n\n#### `--compilation-cache-size=<MB>`\n\n```\n          \\[고급] 컴파일 캐시 디렉터리의 기본 최대 크기를 재정의합니다.\n```\n\n#### `--fail-on-ambiguous-relation-name`\n\n```\n          \\[고급] 컴파일 중에 모호한 관계 이름이 생성되면 컴파일을 실패 처리합니다.\n```\n\n### 컴파일 환경 설정 옵션\n\n#### `--search-path=<dir>[:<dir>...]`\n\nQL 팩이 존재할 수 있는 디렉터리 목록입니다. 각 디렉터리는 QL 팩(또는 루트에 `.codeqlmanifest.json` 파일이 있는 팩 번들)일 수도 있고, 그러한 디렉터리 하나 이상을 포함하는 바로 위의 부모 디렉터리일 수도 있습니다.\n\n경로에 디렉터리가 둘 이상 포함되면, 그 순서가 우선 순위를 정의합니다. 해결해야 하는 팩 이름이 둘 이상의 디렉터리 트리에서 일치하면, 먼저 지정된 디렉터리가 승리합니다.\n\n오픈 소스 CodeQL 리포지토리의 체크아웃을 가리키도록 하면, 그 안에 있는 언어 중 하나를 쿼리할 때 작동해야 합니다.\n\n압축 해제된 CodeQL 툴체인과 형제 위치에 CodeQL 리포지토리를 체크아웃한 경우 이 옵션을 지정할 필요가 없으며, 이런 형제 디렉터리는 다른 방법으로 찾을 수 없는 QL 팩을 찾기 위해 항상 검색됩니다. (이 기본값이 작동하지 않으면, 사용자별 구성 파일에서 `--search-path`을(를) 한 번 설정해 두는 것을 강력히 권장합니다.)\n\n(참고: Windows에서 경로 구분자는 `;`입니다.)\n\n#### `--additional-packs=<dir>[:<dir>...]`\n\n이 디렉터리 목록이 제공되면, `--search-path`에 있는 디렉터리보다 먼저 팩을 검색합니다. 이들 간의 순서는 중요하지 않습니다. 이 목록을 통해 두 곳에서 동일한 팩 이름이 발견되면 오류입니다.\n\n이는 기본 경로에도 존재하는 팩의 새 버전을 임시로 개발할 때 유용합니다. 반면 구성 파일에서 이 옵션을 재정의하는 것은 *권장되지 않습니다*. 일부 내부 작업이 즉석에서 이 옵션을 추가하여 구성된 값을 덮어씁니다.\n\n(참고: Windows에서 경로 구분자는 `;`입니다.)\n\n#### `--library-path=<dir>[:<dir>...]`\n\n```\n          \\[고급] QL 라이브러리의 원시 가져오기 검색 경로에 추가될 선택적 디렉터리 목록입니다. 이는 QL 팩으로 패키징되지 않은 QL 라이브러리를 사용하는 경우에만 사용해야 합니다.\n```\n\n(참고: Windows에서 경로 구분자는 `;`입니다.)\n\n#### `--dbscheme=<file>`\n\n```\n          \\[고급] 어떤 dbscheme 쿼리를 대상으로 컴파일해야 하는지 명시적으로 정의합니다. 이는 자신이 무엇을 하는지 완전히 확신하는 호출자만 제공해야 합니다.\n```\n\n#### `--compilation-cache=<dir>`\n\n```\n          \\[고급] 컴파일 캐시로 사용할 추가 디렉터리를 지정합니다.\n```\n\n#### `--no-default-compilation-cache`\n\n```\n          \\[고급] 쿼리가 포함된 QL 팩이나 CodeQL 툴체인 디렉터리 등 표준 위치의 컴파일 캐시를 사용하지 않습니다.\n```\n\n### CodeQL 패키지 관리자 구성 옵션\n\n#### `--registries-auth-stdin`\n\n쉼표로 구분된 \\<registry\\_url>=\\<token> 쌍 목록을 전달하여 GitHub Enterprise Server 컨테이너 레지스트리에 인증합니다.\n\n예를 들어 `https://containers.GHEHOSTNAME1/v2/=TOKEN1,https://containers.GHEHOSTNAME2/v2/=TOKEN2`을(를) 전달하면\n두 개의 GitHub Enterprise Server 인스턴스에 인증할 수 있습니다.\n\n이는 CODEQL\\_REGISTRIES\\_AUTH 및 GITHUB\\_TOKEN 환경 변수를 재정의합니다. github.com Container 레지스트리에만 인증해야 하는 경우, 더 단순한 `--github-auth-stdin` 옵션을 사용하여 인증할 수 있습니다.\n\n#### `--github-auth-stdin`\n\n표준 입력을 통해 github.com GitHub 앱 토큰 또는 개인 액세스 토큰을 전달하여 github.com 컨테이너 레지스트리에 인증합니다.\n\nGitHub Enterprise Server 컨테이너 레지스트리에 인증하려면 `--registries-auth-stdin`을(를) 전달하거나 CODEQL\\_REGISTRIES\\_AUTH 환경 변수를 사용하세요.\n\n이는 GITHUB\\_TOKEN 환경 변수를 재정의합니다.\n\n### 일반 옵션\n\n#### `-h, --help`\n\n이 도움말 텍스트를 표시합니다.\n\n#### `-J=<opt>`\n\n```\n          \\[고급] 명령을 실행하는 JVM에 옵션을 제공합니다.\n```\n\n(공백을 포함하는 옵션은 올바르게 처리되지 않을 수 있으므로 주의하세요.)\n\n#### `-v, --verbose`\n\n표시되는 진행률 메시지 수를 단계적으로 늘립니다.\n\n#### `-q, --quiet`\n\n표시되는 진행률 메시지 수를 단계적으로 줄입니다.\n\n#### `--verbosity=<level>`\n\n```\n          \\[고급] 상세 정보 표시 수준을 오류, 경고, 진행률, 진행률+, 진행률++, 진행률+++ 중 하나로 명시적으로 설정합니다. \n          `-v` 및 `-q`를 재정의합니다.\n```\n\n#### `--logdir=<dir>`\n\n```\n          \\[고급] 지정된 디렉터리에 자세한 로그를 하나 이상의 파일로 기록하며, 생성된 이름에는 타임스탬프와 실행 중인 하위 명령 이름이 포함됩니다.\n```\n\n(로그 파일 이름을 완전히 제어하려면 대신 `--log-to-stderr`을(를) 제공하고 필요에 따라 stderr를 리디렉션하세요.)\n\n#### `--common-caches=<dir>`\n\n```\n          \\[고급] 다운로드한 QL 팩 및 컴파일된 쿼리 계획과 같이 CLI를 여러 번 실행하는 동안 유지되는 디스크의 캐시된 데이터 위치를 제어합니다. 명시적으로 설정하지 않으면 기본값은 사용자의 홈 디렉터리에 있는 `.codeql`(이)라는 이름의 디렉터리이며, 이미 존재하지 않으면 생성됩니다.\n\n          `v2.15.2`부터 사용할 수 있습니다.\n```"}