Semaphor

Customize table columns

Hide, reorder, rename, resize and sort table columns for yourself, without changing the dashboard for anyone else.

When you view a dashboard, you can arrange a table the way you like it: hide the columns you don't need, put the important ones first, give them names that make sense to you, make them as wide as you need, and sort. Your table is remembered for you, and your downloads match it. Nobody else's table changes.

How to

Customize a table

Anyone viewing a dashboard can do this, in the app or in a dashboard embedded in your product. It works on Table and Detail Table cards.

Top accountsACCOUNTANNUAL REVENUE ▾OWNERSEGMENTNorthwind$412kDanaMidAcme Pacific$388kLuisEntContoso$301kDanaMidFabrikam$254kMeiSMBTailspin$198kLuisSMB1ColumnsSaved to your view only.AccountAnnual revenuewas ARROwnerRegionSegmentNew↺ Reset to defaultDone23451Your columnsA columns icon with a dot. Click itto change your columns again.2Drag to reorderOr focus the grip and pressAlt with Up or Down.3Uncheck to hideOne column always stays visible.4Click a name to renameThe author’s name staysunderneath: was ARR.5NewA column the author added afteryou arranged the table.
Customize columns opens the Columns panel next to the card. The table changes as you go; nobody else's table does.
  1. Open the card's ··· menu and choose Customize columns.
  2. In the Columns panel, arrange the columns:
    • Reorder: drag a row up or down. With the keyboard, focus a row's grip and press Alt with Up or Down.
    • Hide: uncheck a column. At least one column always stays visible.
    • Rename: click a column name and type a new one, up to 120 characters. Press Enter to keep it.
  3. Click Done.

To change a column's width, drag the right edge of its header on the table. Double-click the edge to return the column to the author's width.

The table updates as you go. To start over, click Reset to default in the panel, or choose Reset columns from the card's ··· menu. The table goes back to the way the author built it.

Once you've hidden, reordered, renamed or resized columns, a columns icon with a dot appears in the card header. Click it to open the panel again.

Order the rows

Sort a table

Click a column header to sort by it. Click again to reverse the order. What a sort covers, and whether it's kept, depends on how the table was built.

TableWhat a header sort does
Built in the visual builderSorts all of the data, not only the page you see. The sort is kept.
SQL and Python, loading all rowsSorts all the rows. The sort is kept.
SQL and Python, paging through resultsReorders the rows on the current page only. The sort is not kept.

A sort shows as the arrow in its column header. Even when the author has turned off column customization for a table, you can still sort it; that sort lasts for your visit.

Sort by a change

When a table compares a metric with an earlier period, the change column beside it (the column headed with Δ) sorts too. Click it to rank the rows by how much they moved: descending puts the biggest gains first, ascending the biggest drops.

  • The column sorts by the number it shows first: the change when it shows Change, the percent change when it shows Change %, Both or Ratio.
  • Rows without a change, such as a row with no value in the earlier period, come last in either direction.
  • When the table has a row limit, every row is ranked before the limit applies, so a limit of 10 keeps the 10 biggest movers.
  • The rows are the ones the current period has. A row that had a value only in the earlier period doesn't appear.
  • When the comparison isn't on, for example after the date filter's comparison is turned off, the table sorts by the metric itself.

Wide tables

Pin and move columns

Keep the columns you read by, such as a name or an ID, in view while you scroll a wide table sideways, and nudge a column one place at a time without opening the panel.

  1. Hover a column header and open its ··· menu.
  2. Choose Pin to left to hold the column at the left edge, or Unpin to let it go.
  3. Choose Move left or Move right to move the column one place.
  • Pinned columns keep the table's order: they stay at the left in the order the table shows them. Move a pinned column among the pinned ones; it doesn't cross into the others, and an unpinned column doesn't cross into the pinned ones.
  • Remembered like the rest of your columns: your pins and moves are kept for you, saved in your bookmarks, and cleared by Reset columns.
  • On screen only: pins never change your downloads or PDFs, which keep your column order.
  • Pivoted tables: only the row columns can be pinned. Metrics and their pivoted columns scroll with the table.
  • Comparisons: a comparison column is pinned with the metric it compares.
  • When the author has turned off column customization, you see the author's pins and can't change them.

Only for you

Your table is remembered, and your downloads match it

Your columns, and your sort where the table keeps it, are saved for you on that dashboard. They're there on every visit and on every device. The dashboard itself is never edited.

The author’s tableas built in the editorAccountRegionOwnerARRYour tableRegion hidden, ARR renamed and movedAccountAnnual revenueOwnerYour downloadsCSV of any size, and PDFAccountAnnual revenueOwnerEveryone elsestill sees the author’s tableAccountRegionOwnerARRyoudownloadunchanged
Your arrangement belongs to you: it follows you to every download, and nobody else's table changes.

Downloads use your columns

Once you've customized a table, the Download item in the card's ··· menu says your columns. CSV files of any size and PDFs include only your visible columns, in your order, with your names. PDFs take your column widths as a guide and keep every column readable, so a column you narrowed may print wider.

Scheduled reports send the table as its author built it.

See CSV Downloads for file formats and encodings.

Save several arrangements

To keep your columns together with filters, click selections and the sheet, and to switch between several arrangements, use Bookmarks.

Grouped columns

Pivoted and comparison columns

When a table spreads a metric across several columns, such as one column per month, those columns move together.

Pivoted columns follow their metric

Hiding, renaming or moving the metric applies to all of its pivoted columns. The pivoted columns keep their order.

Row columns stay before the pivoted ones

In a table pivoted by columns, you reorder the row columns among themselves and the metrics among themselves. A new metric order applies in every pivoted group.

Comparisons follow their metric

A comparison column, such as the change from last period, hides, moves and renames with the metric it compares.

Pivoted and comparison columns keep their width

You can resize the other columns. In a table pivoted by columns, that means the columns before the pivoted ones.

Columns the author hid stay hidden

They aren’t available to viewers, so they don’t appear in the panel.

Hiding is not access control

Hiding a column changes what you see, not what data you can access. Your access stays exactly as it was.

Kept or not

Changes that last for this visit only

The Columns panel tells you whether your changes are kept. Usually it says Saved to your view only. When it says Applies to this visit only., your changes apply until you leave the dashboard and aren't saved.

This happens when:

  • the embedded dashboard's token doesn't identify a specific person,
  • the person the token names hasn't been set up yet, or
  • an administrator is viewing the dashboard as another user. They see that user's saved columns, and changes they make don't overwrite them.

How to

Copy a value or a row

Right-click a cell, a total or a Matrix header to copy it (on a link, right-click beside it: the link keeps your browser's own menu). Copying never changes what the dashboard shows.

  • Copy value copies the cell as it reads on screen: the formatted number, the date as shown, a link's address, or a long monospace value in full.
  • Copy row (tables) copies every visible column of the row, in the table's order, separated by tabs, so it pastes into a spreadsheet as one row of cells.
  • The menu also lists what a click on the cell offers, such as filtering the dashboard by it, drilling or seeing its records.
  • From the keyboard, press the menu key or Shift+F10 on a cell to open the same menu.
  • When a table doesn't filter on click, you can reach its cells with Tab, and clicking a cell focuses it: move with the arrow keys, press Cmd+C (Ctrl+C on Windows) to copy the value, or Shift+Cmd+C (Shift+Ctrl+C) to copy the row.

A message confirms each copy. If your browser blocks access to the clipboard, the message says so and nothing is copied; in an iframe embed, add allow="clipboard-write" to the iframe.

For authors

Show values as text, monospace, status or link

How a column shows its values is set by the dashboard's author, in the editor, for everyone.

In the editor, open a column's settings from its header and choose Display as:

Display asShowsUse it for
AutomaticThe value as the table detects and formats itMost columns
TextThe value as plain textCodes that look like numbers
MonospaceA fixed-width font, up to 2, 3 or 5 lines, then Show more; hover for the whole valueError messages, ids, log lines
Number, DateThe value with a number or date formatMeasures and dates
StatusA pill or a dot, in a color you pick for each value: green, red, amber, blue or greyRun states, stages, health
LinkA link to an address built from the value, such as https://example.com/runs/{value}, or from other columns of the row, including hidden onesOpening a record in another tool
ProgressA bar from 0 to 100Completion percentages
  • Monospace, Status and Link are for text columns; a measure keeps its number format.
  • Status colors are your choice per value; a value you haven't given a color shows grey. Colors follow your theme, in light and dark mode.
  • Link shows the full address on hover. Turn on Show an external-link icon to mark links that leave the page. Clicking a link only opens it: it never selects the row or filters the dashboard.
  • To build a Link from another column, click Insert field beside the address and pick it: the menu lists the row's columns by name, hidden ones included, and the preview shows the first rows' links. A field the address names that the card's results don't have is marked, because its links would leave it empty.
  • To link by a value the table shouldn't show, such as a dashboard name that opens https://example.com/dashboards/{dashboard id}, choose Add a field from the data in the Insert field menu (in the card editor, on a table built from fields; on a SQL table, add the column to the SQL and hide it). The field joins the card as a hidden column and goes into the address. On a summary table, rows then group by it too, so two records that share a name stay apart.
  • In a paginated report and its PDF, a Monospace column prints every line.

Agents connected through the MCP set the same options, for example "show the Error column in monospace" or "show Status as green for Succeeded and red for Failed".

For authors

Set the default column order

As the author, you decide the order every viewer starts with. Any column can go anywhere, including a metric between two grouping columns.

  1. Open the card in the visual editor.
  2. On the table preview, open the column's ··· menu and choose Move left or Move right until the column is where you want it.
  3. Save the card.
  • Every table kind: Table and Detail Table cards built in the visual builder, and SQL and Python tables.
  • Your query doesn't change: the order only changes how the table shows its columns. Group-by and metric order in the builder stay as you set them.
  • Pivoted tables: row columns stay before the pivoted columns. Row columns move among themselves, and metrics among themselves: open the menu on any of a metric's pivoted headers, and its new place applies in every pivoted group.
  • Comparisons: a comparison column moves with its metric; its menu moves the metric.
  • Everywhere the table appears: dashboards, documents, CSV and Excel downloads, PDFs and scheduled reports all use your order.
  • Viewers start from it: a viewer who reordered the table keeps their own order; Reset columns returns them to yours.

To pin columns for everyone, open the column's ··· menu in the visual editor and choose Pin to left; Move left and Move right set the order. On a Table sheet, the same menu works on the sheet while you edit the dashboard. Viewers start with your pins, and a viewer who pinned their own keeps theirs.

Agents connected through the MCP set the same order with columnOrder, a list of column names as the outline shows them; the columns it doesn't name keep their places. It saves exactly what a drag in the editor saves, and a move the pivot rule doesn't allow is refused with the reason.

For authors

Turn off column customization

Column customization is on by default for every Table and Detail Table, including tables you built earlier. Turn it off for a table whose columns should stay exactly as you designed them.

  1. Open the card in the visual editor.
  2. Open the table's settings and go to the Columns tab.
  3. Switch off Let viewers customize columns.
  4. Save the card.

Viewers then no longer see Customize columns in that card's menu or resize its columns, and the table opens with your columns, widths and sort. They can still click a column header to sort for their visit.

When viewers have saved layouts for a table, turning this off, or removing the table or one of its columns, shows Affects saved views next to Save while you edit. See which saved views an edit affects.

For developers

Remember columns in embedded dashboards

To remember columns for each person, the token your app requests must name that person: an organization user with orgUserId, or a tenant user who exists in Semaphor with tenantId and endUserId.

Token request
const tokenRequest = {
  projectId: PROJECT_ID,
  projectSecret: PROJECT_SECRET,
  tenantId: 'tenant_acme',
  endUserId: 'user_jane', // the person signed in to your app
};

A token that names only a tenant, or no one at all, still lets people customize columns; their changes last for the visit. To create tenant users the first time they open a dashboard, request the token with endUserEmail, tenantId and autoCreateEndUser: true. See the Token API reference for every option, and Token integration for how a token identifies a person.