쿼리에서 수집(.set, .append, .set-or-append, .set-or-replace)

  • 아티클

이러한 명령은 쿼리 또는 관리 명령을 실행하고 쿼리 결과를 테이블로 수집합니다. 이러한 명령의 차이점은 기존 또는 존재하지 않는 테이블과 데이터를 처리하는 방법입니다.

명령 테이블이 있는 경우 테이블이 없는 경우
.set 명령이 실패합니다. 테이블이 만들어지고 데이터가 수집됩니다.
.append 데이터가 테이블에 추가됩니다. 명령이 실패합니다.
.set-or-append 데이터가 테이블에 추가됩니다. 테이블이 만들어지고 데이터가 수집됩니다.
.set-or-replace 데이터가 테이블의 데이터를 대체합니다. 테이블이 만들어지고 데이터가 수집됩니다.

쿼리 명령에서 수집을 취소하려면 를 참조하세요 cancel operation.

참고

이 수집 방법은 탐색 및 프로토타입 생성을 위한 것입니다. 프로덕션 또는 대용량 시나리오에서는 사용하지 마세요.

사용 권한

테이블에서 다른 작업을 수행하려면 특정 권한이 필요합니다.

  • 명령을 사용하여 기존 테이블에 행을 .append 추가하려면 최소 테이블 수집기 권한이 필요합니다.
  • 다양한 .set 명령을 사용하여 새 테이블을 만들려면 최소 데이터베이스 사용자 권한이 필요합니다.
  • 명령을 사용하여 기존 테이블의 행을 .set-or-replace 바꾸려면 최소 Table 관리 권한이 필요합니다.

권한에 대한 자세한 내용은 Kusto 역할 기반 액세스 제어를 참조하세요.

Syntax

(.set.append.set-or-append | | | .set-or-replace) [async] tableName [with(propertyName= propertyValue [, ...]] <|)queryOrCommand

구문 규칙에 대해 자세히 알아보세요.

매개 변수

이름 형식 필수 Description
async string 지정된 경우 명령은 를 반환하고 백그라운드에서 수집을 계속합니다. 명령과 함께 반환 OperationId 된 를 .show operations 사용하여 수집 완료 상태 및 결과를 검색합니다.
tableName string ✔️ 데이터를 수집할 테이블의 이름입니다. tableName은 항상 컨텍스트의 데이터베이스와 관련이 있습니다.
propertyName, propertyValue string 수집 프로세스를 제어하는 데 사용되는 하나 이상의 지원되는 수집 속성 입니다.
queryOrCommand string ✔️ 결과를 수집할 데이터로 사용되는 쿼리 또는 관리 명령의 텍스트입니다.

참고

관리 명령만 .show 지원됩니다.

지원되는 수집 속성

속성 형식 설명
creationTime string 수집되는 데이터 범위를 만드는 시간에 사용할 ISO8601 문자열 형식의 날짜/시간 값입니다. 지정하지 않으면 now()이 사용됩니다. 지정된 경우 대상 테이블의 유효한 익스텐트 병합 정책의 Lookback 속성이 지정된 값과 일치하는지 확인합니다.
extend_schema bool 이면 true명령이 테이블의 스키마를 확장할 수 있습니다. 기본값은 false입니다. 이 옵션은 .append, .set-or-append 및 set-or-replace 명령에만 적용됩니다. 이 옵션을 사용하려면 테이블 관리 이상의 권한이 필요합니다.
recreate_schema bool 이면 true명령이 테이블의 스키마를 다시 만들 수 있습니다. 기본값은 false입니다. 이 옵션은 .set-or-replace 명령에만 적용됩니다. 이 옵션은 둘 다 설정된 경우 속성보다 extend_schema 우선합니다. 이 옵션을 사용하려면 테이블 관리 이상의 권한이 필요합니다.
folder string 테이블에 할당할 폴더입니다. 테이블이 이미 있는 경우 이 속성은 테이블의 폴더를 덮어씁니다.
ingestIfNotExists string 지정한 경우 테이블에 동일한 값을 가진 태그가 지정된 데이터가 ingest-by: 이미 있는 경우 수집이 실패합니다. 자세한 내용은 ingest-by: 태그를 참조하세요.
policy_ingestiontime bool 이면 true테이블에서 수집 시간 정책이 사용하도록 설정됩니다. 기본값은 true입니다.
tags string 생성된 익스텐트와 연결할 태그 목록을 나타내는 JSON 문자열입니다.
docstring string 테이블을 문서화하는 데 사용되는 설명입니다.
distributed bool 이면 true명령이 쿼리를 실행하는 모든 노드에서 병렬로 수집됩니다. 기본값은 false입니다. 성능 팁을 참조하세요.
persistDetails 지정한 경우 명령이 .show 작업 세부 정보 명령을 통해 검색을 위해 자세한 결과를 유지해야 했음을 나타내는 부울 값입니다. 기본값은 false입니다. with (persistDetails=true)

스키마 고려 사항

  • .set-or-replace는 또는 recreate_schema 수집 속성 중 extend_schema 하나가 로 설정되지 않는 한 스키마를 유지합니다true.
  • .set-or-append 및 .append 명령은 수집 속성이 로 설정되지 않는 한 extend_schema 스키마를 유지합니다 true.
  • 결과 집합 스키마를 대상 테이블의 스키마와 일치시키는 것은 열 형식을 기반으로 합니다. 일치하는 열 이름이 없습니다. 쿼리 결과 스키마 열이 테이블과 동일한 순서인지 확인합니다. 그렇지 않으면 데이터가 잘못된 열로 수집됩니다.

주의

스키마가 수정되면 실제 데이터 수집 전에 별도의 트랜잭션에서 발생합니다. 즉, 데이터를 수집하지 못한 경우에도 스키마가 수정될 수 있습니다.

성능 팁

  • 데이터 수집은 쿼리 실행을 포함하여 클러스터의 동시 작업에 영향을 줄 수 있는 리소스 집약적인 작업입니다. 너무 많은 수집 명령을 동시에 실행하지 않도록 합니다.
  • 수집을 위한 데이터를 수집 작업당 1GB 미만으로 제한합니다. 필요한 경우 여러 수집 명령을 사용합니다.
  • 쿼리에서 distributed 생성되는 데이터의 양이 크고 1GB를 초과하며 serialization이 필요하지 않은 경우 플래그 true 를 로 설정합니다. 그런 다음 여러 노드가 병렬로 출력을 생성할 수 있습니다. 쿼리 결과가 작은 경우 불필요하게 많은 작은 데이터 분할된 데이터베이스를 생성할 수 있으므로 이 플래그를 사용하지 마세요.

문자 제한

쿼리가 문자를 사용하여 엔터티 이름을 생성하면 명령이 $ 실패합니다. 엔터티 이름은 명명 규칙을 준수해야 하므로 수집 명령이 $ 성공하려면 문자를 제거해야 합니다.

예를 들어 다음 쿼리에서 연산자는 search 열을 $table생성합니다. 쿼리 결과를 저장하려면 project-rename을 사용하여 열 이름을 바꿉니다.

.set Texas <| search State has 'Texas' | project-rename tableName=$table

예제

LogsTable과 동일한 스키마가 있고 지난 1 시간의 모든 오류 레코드가 포함되는 RecentErrors라는 새 테이블을 데이터베이스에 만듭니다.

.set RecentErrors <|
   LogsTable
   | where Level == "Error" and Timestamp > now() - time(1h)

"ExtentId"라는 단일 열이 있고 30일 이전에 만들어진 데이터베이스의 모든 범위에 대한 범위 ID가 포함되는 "OldExtents"라는 새 테이블을 데이터베이스에 만듭니다. 데이터베이스에는 "MyExtents"라는 기존 테이블이 있습니다. 데이터 세트가 1GB(100만 개 이상 행)보다 클 것으로 예상되므로 분산 플래그를 사용합니다.

.set async OldExtents with(distributed=true) <|
   MyExtents 
   | where CreatedOn < now() - time(30d)
   | project ExtentId

"ExtentId"라는 단일 열이 있고 30일 이전에 만들어진 데이터베이스의 모든 범위에 대한 범위 ID가 포함되는 현재 데이터베이스의 "OldExtents"라는 기존 테이블에 데이터를 추가합니다. "MyExtents"라는 기존 테이블을 기반으로 하여 tagA 및 tagB 태그로 새 범위를 표시합니다.

.append OldExtents with(tags='["TagA","TagB"]') <| 
   MyExtents 
   | where CreatedOn < now() - time(30d) 
   | project ExtentId

데이터를 현재 데이터베이스의 "OldExtents" 테이블에 추가하거나 테이블이 아직 없는 경우 새로 만듭니다. ingest-by:myTag를 사용하여 새 범위에 대한 태그를 지정합니다. "MyExtents"라는 기존 테이블을 기반으로 하여 ingest-by:myTag 태그로 지정된 범위가 테이블에 아직 포함되지 않은 경우에만 이 작업을 수행합니다.

.set-or-append async OldExtents with(tags='["ingest-by:myTag"]', ingestIfNotExists='["myTag"]') <|
   MyExtents
   | where CreatedOn < now() - time(30d)
   | project ExtentId

현재 데이터베이스의 "OldExtents" 테이블에 있는 데이터를 바꾸거나 테이블이 아직 없는 경우 새로 만듭니다. ingest-by:myTag를 사용하여 새 범위에 대한 태그를 지정합니다.

.set-or-replace async OldExtents with(tags='["ingest-by:myTag"]', ingestIfNotExists='["myTag"]') <| 
   MyExtents 
   | where CreatedOn < now() - time(30d) 
   | project ExtentId

데이터를 현재 데이터베이스의 "OldExtents" 테이블에 추가하고, 만들어진 범위를 만드는 시간을 과거의 특정 날짜/시간으로 설정합니다.

.append async OldExtents with(creationTime='2017-02-13T11:09:36.7992775Z') <| 
   MyExtents 
   | where CreatedOn < now() - time(30d) 
   | project ExtentId

반환 출력

.set 또는 .append 명령으로 인해 만들어진 범위에 대한 정보를 반환합니다.

예제 출력

ExtentId OriginalSize ExtentSize CompressedSize IndexSize RowCount
23a05ed6-376d-4119-b1fc-6493bcb05563 1291 5882 1568 4314 10