list - Selecting Fields

Note

The list clause specifies which fields to display in query results - it's optional (default fields shown) but essential for customizing output.

Overview

The list clause lets you choose exactly which fields appear in your query results. Without list, NQL shows a default set of fields for the table.

Key points:

Optional - Queries work without it (default fields shown)
Flexible - Select any combination of fields
Formatting - Can format values with as() function
Order matters - Fields display in the order listed

Basic Syntax

| list <field_1>, <field_2>, <field_3>, ...

What Can Be Listed

You can list any of these field types:

Native table fields - device.name, operating_system.name
Context fields (from events) - context.os_name, context.location
Computed metrics (from compute clause) - Variables you created
Aggregated metrics (from summarize clause) - Calculated values
Formatted values - Using as() function for display formatting

Common Use Cases

Use Case 1: Basic Field Selection

/* List specific user fields */
users during past 7d
| list username, type

Output:

username     | type
------------ | -----------
jsmith       | regular
adoe         | admin
bwilson      | regular

Use Case 2: After Aggregation

/* List aggregated results */
web.page_views during past 7d
| where application.name == "Confluence"
| summarize avg_load_time = page_load_time.backend.avg() by device.name
| list device.name, avg_load_time
| sort avg_load_time desc

Use Case 3: With Formatting

/* Format values for display */
devices during past 7d
| include execution.crashes during past 7d
| compute crash_count = count()
| list device.name,
       crash_count,
       device.hardware.memory.as(format = bytes)

Use Case 4: Mixed Field Types

/* Combine native, context, and computed fields */
execution.events during past 7d
| compute avg_cpu = cpu_time.avg()
| list device.name,              # Native field
       operating_system.name,     # Native field
       context.os_name,           # Context field (historical)
       avg_cpu                    # Computed metric

Output Formatting with as()

The as() function formats values for better readability:

Available Formats

Format	Use For	Example	Output
`percent`	Percentages	`0.47.as(format = percent)`	47%
`bytes`	File/memory sizes	`memory.as(format = bytes)`	8.5 GB
`bitrate`	Network speed	`bandwidth.as(format = bitrate)`	125.3 Mbps
`currency`	Money values	`cost.as(format = currency, code = USD)`	$2,000
`energy`	Power consumption	`power.as(format = energy)`	1.5 kWh
`weight`	Weight values	`weight.as(format = weight)`	422.5 kg

Formatting Examples

Percentage:

devices during past 7d
| include device_performance.events
| compute cpu_usage_pct = (cpu_usage.avg() * 100) / 100
| list device.name, cpu_usage_pct.as(format = percent)
/* Output: device.name | cpu_usage_pct */
/* LAPTOP-001  | 45% */

Bytes (Memory/Disk):

devices
| list device.name,
       device.hardware.memory.as(format = bytes),
       device.volumes.size.as(format = bytes)
/* Output: LAPTOP-001 | 16 GB | 512 GB */

Currency:

devices
| compute annual_cost = 2000
| list device.name, annual_cost.as(format = currency, code = USD)
/* Output: LAPTOP-001 | $2,000 */

Currency Codes: USD ($), EUR (€), GBP (£), CAD (CA$), CHF (CHF)

Real-World Examples

Example: Device Inventory Report

Scenario: Create a device inventory with key specifications.

devices
| list device.name,
   operating_system.name,
   device.hardware.memory.as(format = bytes),
   device.volumes.size.as(format = bytes),
   device.last_seen
| sort device.name asc

Example: Crash Analysis with Details

Scenario: Show crash details with affected devices.

execution.crashes during past 7d
| summarize
crash_count = count(),
affected_devices = device.name.count(),
affected_users = user.name.count()
  by application.name, binary.real_binary.version
| list application.name,
   binary.real_binary.version,
   crash_count,
   affected_devices,
   affected_users
| sort crash_count desc

Example: Performance Metrics Dashboard

Scenario: Display formatted performance metrics.

devices during past 7d
| include device_performance.events
| compute
avg_cpu = cpu_usage.avg(),
peak_cpu = cpu_usage.avg.max(),
avg_memory = free_memory.avg()
| list device.name,
   avg_cpu.as(format = percent),
   peak_cpu.as(format = percent),
   avg_memory.as(format = bytes)
| sort peak_cpu desc
| limit 50

list is Optional

NQL shows default fields when list is not specified:

/* Without list - shows default fields for users table */
users during past 7d

/* With list - shows only specified fields */
users during past 7d
| list username, type

When to Use list

Use list when you want specific fields or custom order
Skip list for quick exploration (see default fields)
Use list in production queries for consistent output

Field Order

Fields display in the order you list them:

/* Order: device name, then memory, then OS */
devices
| list device.name,
       device.hardware.memory.as(format = bytes),
       operating_system.name

/* Different order: OS, then device name, then memory */
devices
| list operating_system.name,
       device.name,
       device.hardware.memory.as(format = bytes)

Common Patterns

Pattern: Essential Fields Only

devices
| list device.name, operating_system.name, device.last_seen

Pattern: After Aggregation

execution.events during past 7d
| summarize avg_cpu = cpu_time.avg() by device.name
| list device.name, avg_cpu
| sort avg_cpu desc

Pattern: All Computed Metrics

devices during past 7d
| include execution.events
| compute
    avg_cpu = cpu_time.avg(),
    avg_memory = real_memory.avg(),
    execution_count = count()
| list device.name, avg_cpu, avg_memory, execution_count

Pattern: Time-Series Output

execution.crashes during past 7d
| summarize crash_count = count() by 1d
| list start_time, crash_count
| sort start_time asc

Tips & Tricks

Use list with limit for Testing

Verify you're selecting the right fields during development:

devices during past 7d
| include execution.events
| compute avg_cpu = cpu_time.avg()
| list device.name, avg_cpu  # Verify these are the fields you want
| limit 5  # Quick check

Format for Readability

Use as() to make numbers human-readable:

/* Hard to read */
| list device.name, memory
/* Output: LAPTOP-001 | 17179869184 */

/* Easy to read */
| list device.name, memory.as(format = bytes)
/* Output: LAPTOP-001 | 16 GB */

list Doesn't Affect Performance

The list clause only controls display - it doesn't filter data or affect query speed. Use where to improve performance, not list.

Common Mistake: Field Not in Context

/* ❌ WRONG - Field may not be available in event context */
execution.events during past 7d
| list device.hardware.memory  # May not work

/* ✅ CORRECT - Use context field for events */
execution.events during past 7d
| list context.hardware_memory

/* ✅ BETTER - Start with devices for device fields */
devices
| with execution.events during past 7d
| list device.name, device.hardware.memory

Common Mistake: Listing Non-Existent Field

/* ❌ WRONG - Typo in field name */
devices
| list nam, operating_system  # "nam" doesn't exist

/* ✅ CORRECT - Verify field names */
devices
| list device.name, operating_system.name

Tip: See Field Reference to verify available fields.

Field Reference - Available fields per table
where - Filtering Data - Filtering data before display
sort - Ordering Results - Controlling output order
Output Formatting - Complete formatting guide

Additional Resources

NQL Syntax Cheat Sheet - Quick list syntax reference
Common Query Templates - Example queries with list