head (Compute)

When To Use

Use head to keep only the first lines of a table, typically after sort^[1] to keep the top entries: the processes that use the most CPU, the largest tables of a database. To keep the last lines instead, use tail^[2].

Syntax

In a tool, where a parameter sets how many lines the assistant gets:

tools:
  topProcesses:
    description: Lists the processes that use the most CPU, with their PID and CPU percentage.
    parameters:
      count:
        type: integer
        description: How many processes to return, 1 to 999
        default: 10
        pattern: '[1-9][0-9]{0,2}'
    sources:
      processes:
        type: wmi
        query: SELECT Name, IDProcess, PercentProcessorTime FROM Win32_PerfFormattedData_PerfProc_Process WHERE Name <> '_Total' AND Name <> 'Idle'
        namespace: root\CIMv2
        computes:
        - type: sort
          column: 3
          numeric: true
          descending: true
        - type: head
          lines: ${param::count}
    result:
      source: ${source::processes}
      columns: [ name, pid, cpuPercent ]

Properties

Table Transformation Example

With lines: 2:

Recommended Pattern

• Put head after sort^[1] to keep the top lines, and after the filters (keepOnlyMatchingLines^[3], excludeMatchingLines^[4]), so that the lines it keeps are the ones that matter.
• In a tool, let a parameter set lines, bounded by its pattern.

Common Mistakes

• Forgetting that a header line counts as a line: a command whose output starts with a header keeps it among the first lines. Remove it with excludeMatchingLines^[4] when it is not wanted.
• Expecting lines: 0 to keep everything: it keeps no line.