Ingesta de consultas (.set, .append, .set-or-append, .set-or-replace)
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 true es , 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 true es , 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 true es , 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 true es , 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 deextend_schema
ingesta orecreate_schema
esté establecidatrue
en ..set-or-append
Los comandos y.append
conservan el esquema a menos que laextend_schema
propiedad de ingesta esté establecidatrue
en .- 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
marcatrue
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 |
Comentarios
https://aka.ms/ContentUserFeedback.
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea:Enviar y ver comentarios de