Key Columns

A key column is marked with ! and gets a blue header, pinned to the left of the sheet. It's VisiData's equivalent of Excel's frozen identifier columns — but key columns also control sort priority, join matching, pivot dimensions, and multi-column frequency grouping.

Learning Focus

Use ! to mark identifier columns (like id, name) as keys. Key columns stay pinned on the left, control g[ / g] sort order, define & join keys, set Shift+W pivot rows, and group gF frequency tables.

Sample Data Used in This Lesson

hostname,role,status,region
web01,webserver,active,sg
web02,webserver,standby,sg
db01,database,active,kl
cache01,cache,active,sg
monitor01,monitoring,standby,jk

cat > ~/github/practice-folder/visidata/01-loading/servers.csv << 'EOF'
hostname,role,status,region
web01,webserver,active,sg
web02,webserver,standby,sg
db01,database,active,kl
cache01,cache,active,sg
monitor01,monitoring,standby,jk
EOF

vd ~/github/practice-folder/visidata/01-loading/servers.csv

---

Set and Unset a Key Column

!           # toggle current column as key (blue header, pinned left)
z!          # unset key on current column

Example — mark emp_id as primary key:

# Move to 'emp_id' column
!

After:

║ emp_id ║  name    department   region   salary   hire_date
  E001      Alice   Engineering  SG       85000    2020-03-15

The ║ separator marks the boundary between key columns (left) and regular columns (right). Scroll right — emp_id stays visible.

---

Multi-Column Sort with Key Columns (g[ / g])

Mark multiple key columns to control sort priority:

# Move to 'department' column
!           # key column 1 (primary sort)

# Move to 'salary' column
%           # cast to float first
!           # key column 2 (secondary sort, within same department)

# Sort ascending by both
g[

Result — sorted by department, then by salary within each department:

║ department ║ ║ salary% ║   name     region
  Engineering   60000.0     Charlie   SG
  Engineering   85000.0     Alice     SG
  HR            60000.0     Dina      JK
  Marketing     62000.0     Eve       SG
  Marketing     70000.0     Bob       KL

Press g] for descending. Priority order = left-to-right key column order.

---

Key Columns for Joins (&)

When joining two sheets, VisiData matches rows on the key columns. Both sheets must have a key column with the same name.

# Sheet 1: employees (emp_id is key)
# Sheet 2: salaries (emp_id is key)

# Open both sheets
vd employees.csv salaries.csv

# In each sheet, mark emp_id as key:
!   # (do this in both sheets)

# Open Sheets List
Shift+S

# Select both sheets with s
# Press & to join

Join types available:

• Inner join (default): only rows with matching key in both sheets
• Left join: all rows from left sheet, null where no match on right
• Outer join: all rows from both sheets

---

Key Columns for Pivot Tables (Shift+W)

# Set 'department' as key column (pivot row dimension)
!   # on 'department'

# Set 'salary' aggregator
# Move to 'salary' → press %  → press + → Enter: mean

# Open pivot
Shift+W

Result — department as rows, mean salary as value:

department    mean_salary%
Engineering   87500.0
HR            60000.0
Marketing     66000.0

---

Multi-Key Frequency (gF)

# Mark 'department' as key 1
# Mark 'region' as key 2
gF

Result — frequency grouped by department + region combination:

department    region   count
Engineering   SG       2
HR            JK       1
Marketing     KL       1
Marketing     SG       1

---

Bulk Key Column Operations (Columns Sheet)

Shift+C    # open Columns Sheet
g!         # toggle selected columns as key columns
gz!        # unset selected columns as key columns

---

Quick Reference

Key	Action
!	Toggle key column (blue, pinned left)
z!	Unset key on current column
Shift+C → g!	Bulk toggle key for selected columns
g[ / g]	Sort by all key columns ascending / descending
gF	Frequency table grouped by all key columns

Hands-On Practice

vd ~/github/practice-folder/visidata/01-loading/01-employees.csv

# 1. Move to 'department' column → ! → mark as key (blue, pinned)
# 2. Move to 'salary' → % → cast to float → ! → mark as second key
# 3. Press g[ → sort by department, then salary ascending
# 4. Press g] → sort descending
# 5. Press z! on salary → unset salary key (department remains key)
# 6. Move to 'region' → ! → add region as second key
# 7. Press gF → frequency table grouped by department + region

What's Next

• Adding Columns — add blank, derived, and incremental columns
• Column Editing — modify existing column values in-place