Data labels

A data label maps one raw key in your data to a friendlier display name. Your game sends dmg_dealt, and every chart that breaks down by it reads Damage dealt instead.

Think of it as a small dictionary your workspace keeps on the side. Before TopStats draws a chart, it looks up each raw value in that dictionary. If there is an entry, it paints your friendly name. If there is not, the raw value goes on the chart exactly as it arrived.

What a data label is made of

A label is a pair: the raw key, and the name you want on screen.

Two things follow from that shape:

• One label per raw key. A key can only have one display name at a time. Saving a key that already has a label replaces the old name.
• Labels are workspace-wide. The page marks the list Global. Labels are not tied to an environment, a dashboard, or a widget, so production and development read the same dictionary.

What counts as a raw key

Two kinds of raw value end up drawn on a chart, and a label can rename either of them.

The safest way to get the raw key right is to copy it off the chart you want to tidy up. Whatever the legend or the bar reads today is the string to put in the left-hand box.

Where the friendly name shows up

Labels are applied at the moment a chart is drawn, so they appear wherever a widget draws a broken-down value:

• Legends on a chart broken down over time, one entry per series.
• Bar and pie labels on a chart broken down without a time axis. A pie widget is drawn as a donut, and its legend carries the friendly names too.
• Tooltips on those charts, because the tooltip reads the same values.
• The breakdown column when one of those widgets is displayed as a table. It is the column after the row-number column. On a chart broken down over time, the friendly names become the value column headings instead.

Everywhere else keeps the raw value on purpose, so you always have a way back to what your app actually sends:

• The Data labels page itself. The left column is always the raw key.
• The widget builder: the event picker, the Break down by buttons, and the filter rows all work in raw keys and values.
• The heading over the breakdown column, which names the property you broke down by rather than any one value.
• The Events stream and Actors, which show events as they were sent.
• Counter, table, funnel, retention, heatmap, histogram, and KPI widgets, none of which carry a broken-down value to rename.
• Alert rules and their notifications, and emailed digests.
• Everything the API returns, including widget query results.

Why you would use one

You would reach for a label whenever the string that is convenient for your code is not the string you want a teammate to read.

• Readable charts. hp_lost is fine in a payload and unhelpful on a dashboard that a designer or a community manager opens.
• One shared vocabulary. Everyone in the workspace sees the same name for the same thing, instead of each person guessing what an abbreviation meant.
• No code change. You fix the wording in the product, not in your game or your app, so nothing has to be redeployed and no history has to be rewritten.

For example, a game that sends its combat numbers as numeric properties might have a chart broken down by each numeric key whose legend reads dmg_dealt, hp_lost, and gold_earned. Three labels turn that into Damage dealt, Health lost, and Gold earned, and every other chart broken down the same way picks the new names up too.

Or say you break a chart down by a region property that carries short codes. Labelling eu-w, us-e, and ap-s as Europe (West), US (East), and Asia Pacific (South) makes the chart readable without touching a single line of your sending code.

Creating a data label

Labels live on the Data labels page in the sidebar. It is one list of rows, each row a raw key on the left and a display label on the right.

Editing and deleting a label

Both boxes on an existing row are editable in place. Change one and click away from it, and the row saves itself. There is no separate save button.

• Changing the display label updates that mapping and leaves the raw key alone.
• Changing the raw key replaces the mapping. The old key stops being relabelled and the new key takes over the display name.
• Saving a raw key that already has a label overwrites the display name rather than adding a second entry, so you never end up with two labels fighting over one key.

To delete a mapping, select the X at the end of its row. The row disappears and the charts go back to the raw value.

Who can manage data labels

Any member of a paid workspace, including a Viewer, can read the list of labels and see the friendly names on charts. Creating, editing, and deleting a label requires the Developer role or higher, the same split that applies everywhere else in TopStats. See Roles and permissions for the full breakdown.

API endpoints

If you want to manage labels programmatically, these are the paths, all under https://topstats.gg. All three authenticate with a signed-in session, the same one the web app uses, rather than the API key you ingest events with. Every one of them needs a paid workspace and answers a free workspace with a 402.

PUT /v1/labels takes both fields and nothing else:

{
  "eventKey": "dmg_dealt",
  "displayLabel": "Damage dealt"
}

It answers with the saved label, including the id you would pass to DELETE. There is no separate create and update call, so sending the same eventKey twice is safe: the second call just moves the display name. DELETE answers with 204 on success, or 404 if that id is not a label in your workspace.

Related pages