Glossary

Label version

A label version is the name a set of label definitions is published under. Why it keeps records comparable across periods, how to work with two versions in one table and how a new version is announced.

Updated 9 October 20262 min read

A label version is the name a set of label definitions is published under: the values a field can take, such as a company's industry or a posting's job function, and what each value means. Recording it beside each label, as part of data provenance, tells you which definitions a label follows, so labels made at different times can be compared and a change of definitions can be seen.

Why labels need versions

Definitions change: a value is added, two values are merged or the meaning of one is narrowed, and records move between values. Without a version, a change in the count of senior roles could be a change in hiring or a change in the definitions, and nobody could say which. A published name for each set of definitions keeps records labelled under one version comparable with each other, and lets a buyer who built a product on a label decide when to move to the next.

Working with two versions

Store the version with every label you load. Before comparing periods, count rows per version and check whether the new version keeps the meaning of the old keys. Then choose: filter to one version, analyse both and compare, or relabel history yourself. A change in a share across a version boundary deserves a second look. This query shows the postings under each version:

select label_version, count(*) as postings
from job_postings
group by label_version;

Versions in Fokals data

Every labelled record in Fokals data names the version it was labelled under, and the version travels with the record. Job Postings, website labels and Company News each carry it on every row, and the data dictionary lists the values each kind of label allows.

One kind of label can carry more than one current version at once. Current versions share the same values and meanings, so a query written against one reads the others unchanged.

A record keeps its version: a posting until it closes, a website until its labels are next refreshed. No row is labelled again because a later version exists. In Job Postings every key of an earlier version keeps its meaning in the versions after it. A breaking change ships as a new version with at least 90 days' notice, and each new version is announced with its changes.

A label version is named in the data dictionary and in a data manifest, and it is one part of data provenance. Versioned definitions also protect a back-test from silent changes, the concern of point-in-time data.

Frequently asked questions

What happens to old records when a label version changes?

That depends on the vendor's policy, so ask. In Fokals data a row keeps the version it was labelled under: a posting until it closes, a website until its labels are next refreshed. Nothing is labelled again because a later version exists. In Job Postings every key of an earlier version keeps its meaning in the versions after it, so older rows stay comparable on the keys they share, and keys added later sit on rows labelled under the version that introduced them or a later one.

How is a label version different from a dataset version?

A dataset version or release identifies a snapshot of the whole data. A label version identifies the definitions behind one kind of label, and it moves independently of the data. A vendor can refresh data every day under one label version and change that version only when the definitions change. Store both if you need to reproduce an analysis exactly.

How do you know which version a record follows?

Read the version on the row. In Fokals data every labelled row names its version, so you can filter or group by it as in the query above, and the data dictionary lists the values each kind of label allows. When a new version appears in your loads, read its announced changes before you compare periods across it.

The queries and code on this page are examples to adapt. Test them in your own environment before you rely on them.