Ingesta de consultas (.set, .append, .set-or-append, .set-or-replace)

  • Artículo

Estos comandos ejecutan una consulta o un comando de administración e ingieren los resultados de la consulta en una tabla. La diferencia entre estos comandos es cómo tratan tablas y datos existentes o inexistentes.

Get-Help Si la tabla existe Si la tabla no existe
.set El comando devuelve un error. Se crea la tabla y se ingieren los datos.
.append Los datos se anexan a la tabla. El comando devuelve un error.
.set-or-append Los datos se anexan a la tabla. Se crea la tabla y se ingieren los datos.
.set-or-replace Los datos reemplazan a los de la tabla. Se crea la tabla y se ingieren los datos.

Para cancelar una ingesta del comando de consulta, consulte cancel operation.

Nota

Este método de ingesta está diseñado para la exploración y la creación de prototipos. No lo use en escenarios de producción o de gran volumen.

Permisos

Para realizar diferentes acciones en una tabla, se requieren permisos específicos:

  • Para agregar filas a una tabla existente mediante el .append comando , necesita un mínimo de permisos de Table Ingestor.
  • Para crear una nueva tabla mediante los distintos .set comandos, necesita un mínimo de permisos de usuario de base de datos.
  • Para reemplazar las filas de una tabla existente mediante el .set-or-replace comando , necesita un mínimo de permisos de table Administración.

Para obtener más información sobre los permisos, consulte Control de acceso basado en rol de Kusto.

Syntax

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

Obtenga más información sobre las convenciones de sintaxis.

Parámetros

Nombre Tipo Requerido Descripción
async string Si se especifica, el comando devolverá y continuará la ingesta en segundo plano. Use el devuelto OperationId con el .show operations comando para recuperar el estado de finalización de la ingesta y los resultados.
tableName string ✔️ Nombre de la tabla en la que se van a ingerir datos. TableName siempre está relacionado con la base de datos en contexto.
propertyName, propertyValue string Una o varias propiedades de ingesta admitidas usadas para controlar el proceso de ingesta.
queryOrCommand string ✔️ Texto de una consulta o un comando de administración cuyos resultados se usan como datos para ingerir.

Nota

Solo .show se admiten comandos de administración.

Propiedades de la ingesta que se admiten

Propiedad Tipo Descripción
creationTime string El valor de datetime con formato de cadena ISO8601 que se usa en el momento de la creación de las extensiones de los datos ingeridos. Si no se especifica, se usa now(). Si se especifica, asegúrese de que la propiedad Lookback de la directiva de combinación de extensiones vigente de la tabla de destino esté en línea con el valor especificado.
extend_schema bool Si truees , el comando puede extender el esquema de la tabla. El valor predeterminado es false. Esta opción solo se aplica a los comandos .append, .set-or-append y set-or-replace. Esta opción requiere al menos permisos de table Administración.
recreate_schema bool Si truees , el comando puede volver a crear el esquema de la tabla. El valor predeterminado es false. Esta opción solo se aplica al comando .set-or-replace. Esta opción tiene prioridad sobre la extend_schema propiedad si se establecen ambas. Esta opción requiere al menos permisos de table Administración.
folder string Carpeta que se va a asignar a la tabla. Si la tabla ya existe, esta propiedad sobrescribe la carpeta de la tabla.
ingestIfNotExists string Si se especifica, se produce un error en la ingesta si la tabla ya tiene datos etiquetados con una ingest-by: etiqueta con el mismo valor. Para más información, consulte Etiquetas "ingerir por".
policy_ingestiontime bool Si truees , la directiva de tiempo de ingesta se habilitará en la tabla. El valor predeterminado es true.
tags string Cadena JSON que representa una lista de etiquetas que se van a asociar a la extensión creada.
docstring string Descripción que se usa para documentar la tabla.
distributed bool Si truees , el comando ingiere de todos los nodos que ejecutan la consulta en paralelo. El valor predeterminado es false. Consulte sugerencias de rendimiento.
persistDetails Valor booleano que, si se especifica, indica que el comando debe conservar los resultados detallados para la recuperación por parte del comando .show operation details . Tiene como valor predeterminado false. with (persistDetails=true)

Consideraciones sobre el esquema

  • .set-or-replace conserva el esquema a menos que una de las propiedades de extend_schema ingesta o recreate_schema esté establecida trueen .
  • .set-or-append Los comandos y .append conservan el esquema a menos que la extend_schema propiedad de ingesta esté establecida trueen .
  • La coincidencia del esquema del conjunto de resultados con la de la tabla de destino se basa en los tipos de columna. No hay nombres de columna que coincidan. Asegúrese de que las columnas del esquema de resultados de la consulta están en el mismo orden que la tabla; de lo contrario, los datos se ingerirán en las columnas incorrectas.

Precaución

Si se modifica el esquema, se produce en una transacción independiente antes de la ingesta de datos real. Esto significa que el esquema se puede modificar incluso cuando se produce un error al ingerir los datos.

Consejos de rendimiento

  • La ingesta de datos es una operación que consume muchos recursos y puede afectar a las actividades simultáneas en el clúster, incluidas las consultas en ejecución. Evite ejecutar demasiados comandos de ingesta al mismo tiempo.
  • Limite los datos de ingesta a menos de 1 GB por operación de ingesta. Si es necesario, use varios comandos de ingesta.
  • Establezca la distributed marca true en si la cantidad de datos que genera la consulta es grande, supera los 1 GB y no requiere serialización. A continuación, varios nodos pueden generar resultados en paralelo. No use esta marca cuando los resultados de la consulta sean pequeños, ya que podría generar innecesariamente muchas particiones de datos pequeñas.

Limitación de caracteres

Se producirá un error en el comando si la consulta genera un nombre de entidad con el $ carácter . Los nombres de entidad deben cumplir las reglas de nomenclatura, por lo que el $ carácter debe quitarse para que el comando de ingesta se realice correctamente.

Por ejemplo, en la consulta siguiente, el search operador genera una columna $table. Para almacenar los resultados de la consulta, use project-rename para cambiar el nombre de la columna.

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

Ejemplos

Cree una nueva tabla denominada RecentErrors en la base de datos que tenga el mismo esquema que LogsTable y que contenga todos los registros de error de la última hora.

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

Cree una nueva tabla denominada "OldExtents" en la base de datos que tenga una sola columna ("ExtentId") y contenga los id. de extensión de todas las extensiones de la base de datos que se han creado más de 30 días antes. La base de datos tiene una tabla existente denominada "MyExtents". Dado que se espera que el conjunto de datos sea mayor que 1 GB (más de aproximadamente 1 millón de filas) use la marca distribuida .

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

Anexe datos a una tabla existente denominada "OldExtents" en la base de datos que tenga una sola columna ("ExtentId") y contenga los id. de extensión de todas las extensiones de la base de datos que se han creado más de 30 días antes. Marque la nueva extensión con las etiquetas tagA y tagB según una tabla existente denominada "MyExtents".

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

Anexe los datos a la tabla "OldExtents" de la base de datos actual o cree dicha tabla si aún no existe. Etiquete la nueva extensión con ingest-by:myTag. Hágalo solo si la tabla no contiene aún una extensión etiquetada con ingest-by:myTag, según una tabla existente denominada "MyExtents".

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

Reemplace los datos de la tabla "OldExtents" de la base de datos actual o cree dicha tabla si aún no existe. Etiquete la nueva extensión con ingest-by:myTag.

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

Anexe los datos a la tabla "OldExtents" de la base de datos actual mientras establece la hora de creación de las extensiones creadas en un valor datetime específico en el pasado.

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

Salida devuelta

Devuelve información sobre las extensiones creadas debido al comando .set o .append.

Salida del ejemplo

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