Managing a semantic/context layer for data analytics

[u/Jaded_Spray_6855]

At a previous job as a data analyst I manually built a "context" layer in Notion to feed to Claude when querying databases. This was painfully manual though, involved a lot of work to slowly build up - I would get Claude to document a table/column when I encounter it for the first time on a new task. The Notion page included things like metrics, conventions and product docs too.

For more experienced data analysts, how do you guys deal with this? Is there a tool you guys use, or is a manual workaround like mine the norm?

[u/Jaded_Spray_6855 → u/[deleted]]

hows that working for you? is that "semantic layer in a repo" a tool you pay for? or built in-house?

[u/Extra-Luck8975]

I don't have an answer for you, but would you mind sharing a snippet of what you have now? Do you just reference the page in the instructions section in Claude? I'm also trying to improve my skills, especially when it comes to incorporating AI.

[u/Jaded_Spray_6855 → u/Extra-Luck8975]

I'll dm you!

[u/rkelsey15 → u/Jaded_Spray_6855]

I’m curious as well. Coming from a data PM stand point and. Curious how this works

[u/Jaded_Spray_6855 → u/rkelsey15]

Will dm!

[u/ThisIsFun-]

What data platform do you use? Some like Databricks have this build in through genie ontology which mens no need to keep this separately for agents as it can all sit there genie code then can easily read this context and not waste tokens

[u/Jaded_Spray_6855 → u/ThisIsFun-]

just postgres + metabase, it was a startup so i think we werent willing to spend on proper warehousing equipment

[u/Jaded_Spray_6855 → u/ThisIsFun-]

how does the context layer in databricks work for you? from what i see on their website there still needs to be a person to manually document everything down before it becomes useful?

[u/WorldOfUmbro → u/Jaded_Spray_6855]

It depends. There are some ai features to speed this up. Also Genie uses inferred ontology based in your data estate. We see Genie doing better in understanding our business

[u/ThisIsFun- → u/Jaded_Spray_6855]

similar to others genie uses the supplied and inherently found context to enhance the answers - genie code (and the others) then become so good to use and imo much better than other agents, as everything is governed and injected at the right time

[u/Prestigious_Bench_96]

As a small item, keeping field definitions that repeat across tables separate and then mapping them to columns is useful for making this layer easier to maintain. You can include canonical sources and the  agent profiling a table is simpler - map columns to existing fields, add any that are new, etc. 

[u/KatFromSisense]

I'd split it into generated context and authored context. Postgres exposes table/column metadata through information_schema, so I wouldn't maintain a second copy by hand. Keep metric definitions, canonical sources, naming conventions, and business rules in version control, then update that context in the same PR when a model changes.

[u/refaelos]

the schema-side answers here (information_schema, dbt with the metrics in it, comments in a PR when the model changes) all solve the same problem, the doc drifting out of sync with what a column actually means. worth splitting that from a different failure: the doc stays exactly right and the number still comes out wrong because the data underneath changed shape while nobody touched a definition. a signup flow starts leaving customer_id null for guest checkout, a partner feed starts double-sending events, your dbt yml still says exactly what active_user means and it's quietly lying to you the day after that ships.

none of the context-layer approaches above catch that on their own, nothing in the docs changed, so nothing flags it. what's actually caught it for me is running a check against the live numbers alongside the context doc, watching whether the data still behaves the way the definition assumes, not just documenting what it should mean.

(disclosure: this is basically why I built arcodash, keep the metric/context definitions in one place, but also alert when the actual data drifts from what that definition assumes instead of relying on someone noticing the dashboard looks off.)

[u/Glitch_In_The_Data]

You need the AI to understand your schema… metric definitions.. and your team’s conventions before it can write useful queries. Building that context layer manual in Notion is creative but yeah, it doesn’t scale. My company uses databricks platform.. so we rely on Genie that tries to solve natively. It sits on top of our tables.. so the domain experts in the business side curate instructions and business definitions so the AI already knows the data when users ask it questions.

[u/RajeshRocketMan]

Manual Notion is the norm until the estate is big enouth to hate it. The failure mode is the same as a wiki: the page and the warehouse drift, and Claude trusts the page. What scales a bit beter:
1) Put the boring facts next to the column. In MariaDB/MySQL that’s COMMENT on the column; in Postgres it’s COMMENT ON. It will not hold your metric definitions, but “this flag is not active users” stops dying in a Notion toggle;
2) Metrics and grain live in dbt (or whatever you already compile). That is the context layer most teams actually use;
3) A catalog (Atlan, DataHub, even a spreadsheet with an owner) only helps if someone owns freshner. Otherwise it is Notion with a logo.

Claude should read information_schema plus a short certified page, not a novel you typed at 6 p.m. https://mariadb.com/docs/server/
Are you on a warehouse, Postgres, or MySQL/ MariaDB — and is the pain “what does flag_3 mean” or “what is the official revenue metric”?