Compartir a través de

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

  • Artículo

Se aplica a: ✅Microsoft Fabric✅Azure Data Explorer

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.

Comando 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 desde el comando de consulta, consulte cancel operation.

Nota:

La ingesta de la consulta es una ingesta directa. Por lo tanto, no incluye reintentos automáticos. Los reintentos automáticos están disponibles al ingerir a través del servicio de administración de datos. Use el documento de información general de ingesta para decidir cuál es la opción de ingesta más adecuada para su escenario.

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 ingesta de tablas.
  • Para crear una tabla con 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 administrador de tablas.

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

Sintaxis

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

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

Parámetros

Nombre Type Obligatorio Descripción
async string Si se especifica, el comando devuelve inmediatamente y continúa 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. Solo .show se admiten comandos de administración.

Consejos de rendimiento

  • Establezca la distributed propiedad true en si la cantidad de datos generados por 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 puede generar innecesariamente muchas particiones de datos pequeñas.
  • La ingesta de datos es una operación que consume muchos recursos que puede afectar a las actividades simultáneas en la base de datos, 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.

Propiedades de la ingesta que se admiten

Propiedad Tipo Descripción
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.
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 administrador de tablas.
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 ambos. Esta opción requiere al menos permisos de administrador de tablas.
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 usada para documentar la tabla.
persistDetails Valor booleano que, si se especifica, indica que el comando debe conservar los resultados detallados para la recuperación mediante el 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 ingesta extend_schema 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.

Limitación de caracteres

Se produce 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 ingest 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 identificadores de extensión de todas las extensiones de la base de datos que se crearon hace más de 30 días. 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 datos a la tabla "OldExtents" de la base de datos actual, al establecer la hora de creación de extensiones en una fecha y hora específica 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