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

Estos comandos pueden ejecutar una consulta o un comando de control e ingerir los resultados de la consulta en una tabla. La diferencia entre estos comandos es cómo tratan a las tablas y los 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.

Nota

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

Sintaxis

.set[async] TableName [with(PropertyName=PropertyValue [, ...])] <|QueryOrCommand

.append[async] TableName [with(PropertyName=PropertyValue [, ...])] <|QueryOrCommand

.set-or-append[async] TableName [with(PropertyName=PropertyValue [, ...])] <|QueryOrCommand

.set-or-replace[async] TableName [with(PropertyName=PropertyValue [, ...])] <|QueryOrCommand

Argumentos

  • async: si se especifican, el comando se devuelve inmediatamente y continúa la ingesta en segundo plano. Los resultados del comando incluirán un valor OperationId que se puede usar con el comando .show operations para recuperar el estado y los resultados de la finalización de ingesta.
  • TableName: el nombre de la tabla en la que ingerir datos. El nombre de la tabla siempre está relacionado con la base de datos en contexto.
  • PropertyName, PropertyValue: cualquier número de propiedades de ingesta que afectan al proceso de ingesta.

Propiedades de ingesta que se admiten.

Propiedad Descripción
creationTime 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 utilizará el valor actual (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 Valor booleano que, si se especifica, indica al comando que extienda 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. Las únicas extensiones de esquema permitidas hacen que se agreguen columnas adicionales a la tabla al final.
recreate_schema Valor booleano que, si se especifica, describe si 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 propiedad extend_schema si ambas están establecidas.
folder Carpeta que se va a asignar a la tabla. Si la tabla ya existe, esta propiedad sobrescribirá la carpeta de la tabla.
ingestIfNotExists Valor de cadena que, si se especifica, impide que la ingesta se realice correctamente si la tabla ya tiene datos con la etiqueta ingest-by: con el mismo valor.
policy_ingestiontime Valor booleano. Si se especifica, describe si se habilita la directiva de tiempo de ingesta en una tabla que este comando crea. El valor predeterminado es "true".
tags Cadena JSON que representa una lista de etiquetas que se van a asociar a la extensión creada.
docstring Cadena que documenta la tabla.

Propiedad que controla el comportamiento del comando.

Propiedad Tipo Descripción
distributed bool Indica que el comando ingiere de todos los nodos que ejecutan la consulta en paralelo. El valor predeterminado es "false". Vea los comentarios más abajo.
  • QueryOrCommand: Texto de una consulta o un comando de control cuyos resultados se usarán como datos para la ingesta.

Nota

Solo se admiten los comandos de control .show.

Comentarios:

  • .set-or-replace reemplaza los datos de la tabla, si esta existe. Quita las particiones de datos existentes o crea la tabla de destino, si esta aún no existe. El esquema de la tabla se conservará a menos que una de las propiedades de ingesta extend_schema o recreate_schema esté establecida en "true". Si se modifica el esquema, sucede antes de la ingesta de datos real en su propia transacción. Un error en la ingesta de datos no significa que el esquema no se haya modificado.
  • .set-or-append y .append los comandos conservarán el esquema a menos que la extend_schema propiedad de ingesta esté establecida en "true". Si se modifica el esquema, sucede antes de la ingesta de datos real en su propia transacción. Un error en la ingesta de datos no significa que el esquema no se haya modificado.
  • Se recomienda limitar los datos para la ingesta a menos de 1 GB por cada operación de ingesta. De ser necesario, se pueden usar varios comandos de ingesta.
  • 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 este tipo al mismo tiempo.
  • Al hacer buscar que el esquema del conjunto de resultados coincida con el de la tabla de destino, la comparación 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. En caso contrario, los datos se ingerirán en la columna equivocada.
  • Resulta útil establecer la marca distributed en "true" cuando la cantidad de datos que genera la consulta es grande, supera 1 GB y la consulta no requiere serialización, por lo que varios nodos pueden generar resultados en paralelo. Cuando los resultados de la consulta son pequeños, no use esta marca, ya que podría generar innecesariamente muchas particiones de datos pequeñas.

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