다음을 통해 공유

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

  • 아티클

적용 대상: ✅Microsoft Fabric✅Azure Data Explorer

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

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

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

참고 항목

쿼리에서 수집은 직접 수집입니다. 따라서 자동 재시도는 포함되지 않습니다. 자동 재시도는 데이터 관리 서비스를 통해 수집할 때 사용할 수 있습니다. 수집 개요 문서를 사용하여 시나리오에 가장 적합한 수집 옵션을 결정합니다.

사용 권한

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

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

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

구문

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

구문 규칙에 대해 자세히 알아봅니다.

매개 변수

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

성능 팁

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

지원되는 수집 속성

속성 Type 설명
distributed bool 이 경우 true명령은 쿼리를 실행하는 모든 노드에서 병렬로 수집됩니다. 기본값은 false입니다. 성능 팁을 참조하세요.
creationTime string 수집된 데이터 익스텐트의 생성 시간에 사용할 ISO8601 문자열 형식의 datetime 값입니다. 지정하지 않으면 now()이 사용됩니다. 지정된 경우 대상 테이블의 유효한 익스텐트 병합 정책의 Lookback 속성이 지정된 값과 일치하는지 확인합니다.
extend_schema bool 이 경우 true명령은 테이블의 스키마를 확장할 수 있습니다. 기본값은 false입니다. 이 옵션은 , .set-or-append및 set-or-replace 명령에만 .append적용됩니다. 이 옵션을 사용하려면 테이블 관리자 이상의 권한이 필요합니다.
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 테이블을 문서화하는 데 사용되는 설명입니다.
persistDetails 지정한 경우 명령이 .show 작업 세부 정보 명령을 통해 검색에 대한 자세한 결과를 유지해야 임을 나타내는 부울 값입니다. 기본값은 false입니다. with (persistDetails=true)

스키마 고려 사항

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

주의

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

문자 제한

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

예를 들어 다음 쿼리에서 연산자는 search 열을 $table생성합니다. 쿼리 결과를 저장하려면 프로젝트 이름 바꾸기를 사용하여 열의 이름을 바꿉니다 .

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

예제

지난 1시간 동안의 모든 오류 레코드와 동일한 스키마 LogsTable 를 가지고 있는 데이터베이스에 호출 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