Агентная аналітыка — гэта больш, чым text-to-SQL: урокі Anthropic
Што публікацыя Anthropic пра аналітыку самаабслугоўвання кажа пра семантычныя пласты, навыкі, ацэнкі і падмурак даных, і чаму адзін text-to-SQL стварае ілюзію дакладнасці.
Крыніцы: Anthropic is telling you that Agentic Analytics is not just text-to-SQL
Аналітычныя “сметаны” — гэта новыя “сметаны” AI
Паста з 3 чэрвеня 2026 года ад Anthropic працою самаслужбовых аналізаў паведамляе ў грамадскай сферze тое, што багатыя команды з дадзеннямі выучылі на скасце: агентныя аналізы не ўсё тое ж самае, што проста направіць Claude Code да базы дадзенняў і запытаць яе пра ўсё.
Большасць людзей знае тэрмін “сметаны AI”. Аналітычныя “сметаны” — гэта іх роднік. За дапамогою агента-праграміста кожны можа зараз падключыцца да базы дадзенняў і ствараць аналітычныя справаздачы. Гэта чудова для зніжэння бар’еру для входу, але з іншай стороны, практычна ніхто не перакантролюе цыфры. Дашборды прыходзяць у вачынку .html, сторунках Confluence чы ў скрыншотах тэрміналу, і малая частка з іх была перакантролювана. Прычына — хуткая пачуць безпекі. Адколі LLM-ы так добра перакладаюць англійскую мову на SQL, выдумкі павінны быць правымі, такая ў нас думка.
Гэта абыякласна павера. Калі аналітыка зводзіцца да стварэння запытанняў, проблема адбіваецца занадта вузка, а супакоўвальная інфраструктура застаецца непазіранай, хоць самэ ёй і дакладваецца, чы розглядваная адпаведзь спадкуючы ці шкодзячы. Сам дызайн Anthropic размешчае фундаменты дадзэў, адказвальныя канстанты, навыкі і працэсы паўтарной перапрацоўкі дадзэў дае ў пачатковым етапе, яшчэ перш чым Claude бачыць запытанне. У пастае перыякі класычных практык інжынерыі дадзэў наводзяцца як обовязковыя трэбовання, а таксама даўаюцца урокі, каб іншыя команды моглі ухіліцца ад памылак.
Эта публікацыя ўжо не науковая праца, а артыкул пра Enterprise AI; пры тым яна ўваходзіць у чысло найяснейшых аналізаў практычнага застосоўвання, якія апісваюць, што неабходна для паважальных агентных аналітых рашэнняў. У статыце па парадку розглядаюцься галоўныя ідэі: чаму падход «тэкст-у-SQL» ўсупершцы не падходзіць, звядзе дзеяўся неодназначнасць, што створыла компанія Anthropic, што павінна існаваць перш чым будзе напісана запітанне, ролі семантычнага шару і навыкаў, чаму важлівыя ацэнкі і тыпавое выкарыстоўванне, а таксама з чаго можа пачаць команда.
Чаму «тэкст-у-SQL» прывлекае так многа ўвагі
Стварэнне запытаў — гэта і частка, яю можна прадказаць за трыдзесят секундаў. Задайце запыт простаю англійскай мовай, пазірьце, як мадэль запішае запыт, запрацюе яго з базай дадзенаў і дастане цячыну або графік. Гэта выглядае чародзкі, асобліва для нефаховых людзей, якія раней завышаліся на команду аналітых спецыястаў чы ўжо створаныя панелі керування.
Прыгкія адказы ад Claude чыра Codex нічога не сказываюць пра тое, чы роўна запытанне было адпаведна адпаведзена. Па словам Anthropic, нарабаткаець Claude на задачу з складам можа стварыць хыбны адчуцьня тачнасці, і гэта ўсё тая пастка.
Возьмімо прыклад, калі адносіб пытаецца: «Калі быў актыўны дохад ад кліента ў мінулы месяц?» Аналітычныя нюансы пачынаюцься ведаў:
- Што значыць, калі кліент ўважаецца актыўным?
- Калія ўзгляд на кліента ёсць афіцыйным?
- Гэта ўсего дохад чы чысты дохад?
- Калія палата даты паслужыць?
- Калія вярненні, фільтры працэсаў мошчанства чы аўтаскасы продуктав должны быць застосаваны?
Функцыя перакладу тэксту ў SQL прыходзіць толькі пасля таго, калі гэтыя рашэнні ўжо прыняты. Таму надзеяны агент для аналізу патрэбуе цэлай інфраструктуры, якая керуе яго розуменнем бізнесу.
Гэта адаптаванне вядомай студзіі Google пра супакрытых тэхнічных боргаў у сістэмах машыннага навчання, якая паказала, што мадэль — гэта маленькі блок унутры набагато большай структуры працы з машынным навчанням у практычных цілях.
Рысунак вышэй — гэта скрыншот з той студзіі. Той жа картына застосоўваецца і да агентаў для аналізу, калі маленькі чорны блок заменяецца на прыемнік тэксту ў SQL.
Адказ Anthropic паспаўляе з гэтым падходам, як у фразе "Даныя — гэта не програмнае забезпечэнне". Работа з аналізам мае іншы характар, чым функціі програмнага забезпечэння. Зазвычай існуе адна правільная адказ з аднаго правільнага крыніцы, пры тым не існуе паводлівага спосабу падтвердзіць яго толькі на адпаведным выніку. Кроме таго, сістэма можа напісаць бездоганны SQL, але цэлкам не разумець яго бізнес-значэння.
Anthropic таксама прыладзіла набор прыкладоў, якія парадрожнаюць гэтыя два падходы, якія паказаны ў ніжэйшай табліце.
Anthropic класіфікуе выйшлыя неудачы на тры тыпы:
- Неясна сутнісна або структурная характэрыстыка паняцце. Корыстувач выказваеся «актыўныя корыстувальнікі», «дохады» або «задаваленасць», і агенту неабходна выбраць аднойчы з калькольных варыянтаў рэалізацыі. Разлікі часта настолькі тонкія, што неправільны адказ застаецца прыемным з точкі зору професійнасці.
- Застарэласць дадзеных. Дакументацыя, табелі і бізнес-правіла постаўляюцься змянамі. Показнік, які быў правільным тры тыдзены тыму, можа некалькі разоў стаць неправільным пасля змены схемы, адключэння новага правіла або перабудовы панелі керування.
- Неспроможнасць адшукання. У якім-небудзь элеменце сістэмы існуе правільны адказ, але для пошуку трэба пераглянуць занадта велікі об’ём інфармацыі. Мадэль працягвае робіць вывады на аднойчы з блізкіх, але неправільных дадзеных.
Сам склад не можа рашыць жаднае з эйх проблем. Ён зберагае даны, а не цэлы сэнс бізнесу, які распадаецца на вызначэнні метрык, сэмантычныя мадэлі, засцярогі, стандарты команды, адпраўніцтва і історыю. У прыкладзе з доходамі напісаць GROUP BY — гэта проста. Аднак выбіраць, што значыць „актыўны“, — складна: адна пакупка за трыдцьць дзён, оплачаная некрадучаяся выкарыстоўка за перыод выкладкі, або праграда, спецыфічная для домэна, якая існуе толькі на сэмантычным роўні.
Таму пытанне пра тое, чы можа Claude напісаць SQL, яе ўжо не така цікавая, адколі ён, верагодна, пісае яго лепшая, чым большасць людзей. Корыстнае пытанне — што саме Anthropic было прымушана стварыць наваколо Claude, каб гэтыя проблемы больш не домінавалі над рэзультатам.
Што стварыла Anthropic
Адказ — гэта сукупнас перавярэнайх інжынерскай практыкі і дадзеных слоёў, якія робяць можлівымі дзеяння агентаў. Па сутнасці, гэта цэлыя сістэма, у якой Claude выступае як інтэрфейс зверху, а ўсё інша знаходзіцца пад яго. У статыце ёй парадкавана на чатыры часты:
- Фундаменты дадзеных, тое ў значэнні канонічных набораў дадзеных, модэляў дадзеных, прыемаў ператварэння, тэстаў, пераканальніх пераглядоў і метададзеных.
- Адказвальныя джэрэлы, якія включаюць семантычны слой, лініюяж дадзеных, бізнес-кантэкст і рэтэльна падготавленыя кансультатывныя матэрыялы, якія дапамагаюць прыладзець запіт да правільнага значэння.
- Навыкі, якія ўключаюць процедуры конкрэтнай галіны, якія паведамляюць модэлю, як працаваць, а не толькі якія дадзеныя існуюць.
- Парадаканаленне, якое включае офлайн-ацэнкі, онлайн-пераканальнія перагляды, выявленне паходжэння дадзеных і цыклы адтрымання ў стацыонарны стан.
Знімак экрана вышэй прыняты з паслявідання Anthropic. Паглянце, дзе ў лямоце знаходзіцца SQL: пасля всіх складных рашэнняў. Калі мадэль нарэшце запісвае запіт, стак ужо сузіў значэнне пытання і вялікі шлях, які заслуговае на дазвер'е.
Гэтая структура лепшая адбівае цыфру з загалоўка, чым выбор мадэлі. Калі прачытаць каротка, 95 процэнтавых цыфраў здаюцца показнікам мадэлі, а калі прачытаць атрыбутавана, стае зрозумела, што гэта показнік сістэмы, вялікая частка паслявідання якога апісвае інструменты, якія вікорыстоўваюцца з Claude, а малая — самога Claude.
Што павінна існаваць перш чым будзе запісаны любы SQL
Компанія Anthropic чытко зазначае, што стандартні методы інжэнерыі даных все шчэ застосовуюцца: мадэлявання розмірностэй, перэвіркі свіжосты і повноты даных, канонічні наборы даных, готові до вікорыстання, і чыткі словнікі даных. Усе гэта залішаецца актуальнім, навіць калі інтэрфейс стае більш дыялоговім. Ба більшэ, значушчысць цых практык зростае, оскількі корыстувач цяпер ёсць агентом, які дые на основі запітання людыні. Аналітык іноды можа помітыты, што табліця мае проблемі, тоды як агент можа значно швідшэ скорыгуваты хібні прыпушчэння.
Ёсць певна іронія в тому, што компанія з сферы перэдовіх тэхналогій повідомляе світ про необхіднісць традыційноі інжэнерыі даных для агентаў. Жодна з цых практык не ёсць новою, і будзь-якая двадцятырычна кніга з тэмі зберыгання даных дае таку саму пораду. Іх все шчэ варто повторуваты.
Канонічні наборы даных
Невялыя групы логічных модэляў, якія строга кантролююцца, пры чым кожны з іх являецца ўнікальным адказам на запыт, зменшаюць колькасць правдападобных адказоў ўжо да пачатку ўзяць даныя. Можа знадобіцца разныя рэвэлюцыі аграгавання, але ўсе вырахункі завжды павінны вестыся на аснове гэтай невялкай базы. То ж самае стосуецца аналітычных агентаў: калі яны можаць доступваць толькі да калькі надзеяных набораў даных і знаюць, як гэтыя наборы адносуюцца да расшырэных вымераў, шансы на выбір няправільнага крыніцы рэзка сякрацяюць.
Метаданы як продукт першага класу
Метаданы даўаюць агенту працоўную апісацыю табелей, столбцоў, ступеня дзеярожнечы, ўласнікаў і абмежэнняў. Калі ніхто не документуе модэль, значэнне кожнага столбца, а таксама лініяй з’яеднання чы клучы, то LLM запэўняе кожную праслойку за дапамогою спадчыных прыпускаў.
Зберагчыце модэлі, дакументы, панелі керування і файлы навыкаў разам
Колакявацыя можа проста значыць вялікі манорэпо, але Anthropic апісвае ўсё бол шчырэ. Паўнае большасць коду дадзеных, ад мадэлявання і семантычнага шару да дакументацыі і стандартных візначэнняя панелей керування, знаходзіцца ў аднам рэпазітарыі, які захоўваецца за дапамогою перакрыцчаў CI, якія контролююць цэліснасць між шарамі. Будзь-яя змяна ў мадэлі, якая могла бы зламаць панель керування або зробіць недзейнаю задокументаваную метрыку, фіксуецца перакрыцчам CI, а выправленне падае ў той жа pull request.
Гэта спростаўляе лёгкаважную тэзу, што аналітыка AI зменшае значэнне інжынерыі дадзеных. Чым больш пытанняў праходзіць праз мадэлі, тым болей візуабельным стае калітэт мадэлявальнага шару.
Іншыя прадаўцы таксама яго адображаюць. Сэмантны слой dbt існуе таму, што апісанні метрык прабываюць напісаныя раз і вікорыстоўваюцца кожным інструментам. Microsoft радзіць падготавіць даны Power BI для Copilot з схемамі, гатовымі да AI, перакананымі адпаведзямі і чысткімі інструкцыямі, каб модэль могла адпавядаць на аснове рэальнага кантэксту. Snowflake стварыла Cortex Analyst на аснове сэмантных модэляў і перакананых запытаў, з контралем на этапы генеравання SQL. Кожны продукт выявляе адно і тое ж: кантэкст, падготавлены загадзя, ёсць часткай адпаведзі.
Сэмантны слой — гэта карта агента
Семантычный слой — гэта архітэктурный мост, які ператвараець неапдортаваныя, складныя даны на знакомыя бізнес-тэрміны, показнікі і асоцыяціі. Ён знаходзіцца межа складчыкамі зберагачаў даных, такімі як Snowflake, Databricks чыста BigQuery, і інструментамі для ўжывання даных, такімі як Power BI, Tableau чыста AI-агенты. За дапамогою такога слоя можна адпаведзець на пытанні пра значэнне столбца, тып іншага столбца, спосаб расчытку показніка, а таксама пра тое, як функцыонуют іерархіі і асоцыяціі межа табліцамі.
На вышэйшым дыяграме паказана месца, дзе знаходзіцца гэты слой. Anthropic спрыяе таму, каб ён быў такім цэнтральным, што агенты ў яе сістэмах за структурныя прычыны вынужданы спачатку кансультавацца з семантычным слоем. Асновны прынцып заключаецца у тым, што мадэль выклікаецца з чыстаўленага значэння, а не з безцэльнага аналізу сырых табелей. Anthropic ідzie ўсё далей і называе паслабай практыкай тое, калі агенты самі ствараюць семантычны слой. Людзі застаюцца неабходнымі для таго, каб ён заставаўся якісным, і гэта прыходзіць ад аднаго з найпрамоўнейшых лабораторных центраў у свеце.
Промышленнае сектара прагне да дася да адпраўніцца да адной і той жа пазыркі. Cortex Analyst ад Snowflake выкарыстоўвае семантычны модэль для з’яеднання бізнес-запытак з структураю базы дадзеных. Genie ад Databricks выкарыстоўвае экспертаў у паводзе, каб тыя стваралі наборы дадзеных, інструкцыі, прыклады SQL-кода і кантэкст бізнесу. dbt зберагае логіку метрык у аднам месцы, тады інструменты, якія працуюць пасля ўжо не трэба яе перзастраіваць, а Microsoft перакладае падтверджаныя адказы і інструкцыі ІІ у модэль BI. Агенту для наукі пра дадзеныя ад Google таксама была патрэбна што-і падобнае — псевдасемантычны слой пад назвай Analyzer, перш чым яго рэзультаты сталі эфектываўскімі.
Без такой карты агент толькі здагадваецца. З яё модэль спяшае своі зусілля на разумовыя выводы ў межах вядомага свету і не стварае яго з нуля.
Прыклады запытак дапамагаюць падготавіць слой
Anthropic паведамляе, што корпус запітоў, тыябо історыя SQL-запытак з панелей керування, нотабукіў і попярэдніх аналізаў, можа мець позытывны чысты эфект. Кантактнае меса не ў тым, каб падаваць яго агенту у необработаны фармат. Уместа таго корпус запытоў ператвараецца на структураваныя документы-справакі па кожнай галіне і на шаблоны аналіза, якія можна перадваражыць. Історыя запытоў выступае як сырой матэрыял для адбору, а не як первынны джэрэла інформацыі, якое агент чытае безпосерэдна.
Існуе таксама практычныя наследкі для таго, хто володзіць чым. Пакалькі агент аналітыкі спалюецца на кераваныях вакладзеннях, людзі, які падтрымляюць гэтыя вакладзення, зазвычай інжынеры аналітыкі і власнікі домэнаў, стаюць часткаю історыі якасці агента. Спарчованая метрыка перастае быць аргументам пра панелі керавання і стае дыфектам у спакульнай шарэ, які лячыцца ў адным месцы і фіксуецца кожным спожывачам, чалавекам або модэлем. Команды, якія вядуць работу такім чынам, знайдуць, што пераход на агентов прыемнае для ўсіх, у працоўніку з метрыкай, логіка якой рассеяна ў нотбукі і інструментах BI.
Чаму навыкі так сільна вплываюць на тачнасць
Семантычны шар поясняе, што значыць свет, але не як дзейваць у ўсім гэтым. Ён не можа сказаць, якія крокі выконвае хорашы аналітык, калі зацікавленая сторона задае неясны вопыт, які мае два можлівых крыніцы і вядомы крайній прыклад у адзінай рэгіян.
У сістэме аналізу Anthropic навыкі функцыонуюць як закодаваныя інструкціі для аналітыкаў, а не як дакументацыя. Яны маюць у сабе процедурныя знання:
- парадокс, па якому пераключаюцца джэрэлы
- момент, калі трэба вікорыстоўваць семантычны шар і дзе дазволена альтэрнатыва
- якія пытанні для яснаць інформацыю трэба задаць заінтэрэсаваным сторонам
- обмежэння, якія дыюць у данай галіне
- спосаб прызначэння сумневаў ў рэзультатах пры яго падтрымцы
- дэталі походжання, якія включаюцца ў фінальную адпаведзь
Самыя вялікія рэзультаты Anthropic апраноцаваны звяжаныя з гэтым. За данымі раздзелу пра навыкі, Claude без іх ніколі не досягаў 21 процэнта пад час аналізу. З вікорыстанням шара навыкаў точнасць у суме паднялася да 95 процэнта, а ў дзеярых галінах — да прыбліжна 99 процэнта.
Гэты показнік змінюе тое, як слід назіваты сістэму. Калі найбольшы зміні відбуваюцца завдзякі процедурному керывніцтву, а не крашчый генераціі SQL, тады гэта не ёсць продуктом тыпу «тэкст → SQL». Гэта продукт аналітычного робочого працэсу з віконанням запітыв усерэдыні.
Таксама корысно пам’ятаты, чым не ёсць гэтая навічка. Гэта не довшый сістэмній запіт, і гэта не набір прыкладніх запітыв. Гэта підтрымуваній артэфакт з версіею, умовою запуску і візначэною процедурою, якая завантажуецца, колі гэта необхідно. Гэта дозволяе іі перэглядаты у запіты на зміні, тэстуваты проты набору даных для оцінкі і легко відаляты, колі змінюецца базова мадэль даных.
На зображэнні ніжчэ показана шаблон навічкі, яку вікорыстовуе Anthropic.
Разом ці артэфакты становляць повне візначэння, а додаток містыць усю шаблону.
Оцінкі і обслуговування маюць таке ж значэння, як і запіты
Нават агент для аналізу з моцным фундаментам з часам паслабляецца. Калі ўжо існуюць семантычныя шары, падобраныя прыклады і навыкі, наступной проблемай становіцца ўхіл: табелі зменяюцца, ваказанні перасуваюцца, панелі керавання перабудовуюцца, а навыкі больш не падходзяць да вачоўскага модэлю. Пратакт, які ўчора быў правым, завтра стае застарэлым кантэкстам.
Anthropic прыводзіць яскравы прыклад: точнасць у рэжыме «офлайн» за адзін месцовы паднялася з апошніх 95 процэнтав да апошніх 65 процэнтав, пераштоўкі ўтрымання навыкаў пачалі спрацоўваць як інжынерная проблема. Гэтыя цыфры ператвараюць утрыманне на трэбавання да надзеяння, а не проста на додатковую практыку.
У аналітыкі ёсць практычная прыемка — магчымае ацэнкаваць рэзультаты на адпраўленых цыфрах, якія павінны быць отрыманы будзь-якім правільным працэсам. Калі гэта візначана, усе іншыя параметры сістэмы можна налаштаваць па ўзору гэтых цыфраў. Команда можа прыкладзіць другую версію навыку з вікорыстаннем Haiku, Sonnet чыў Opus на розных роўнях аналізу, параганаваць точнасць і выбраць той варыянт, які найлепша сантэзуе вартасць і якосць — чы то достатня точнасць за ніжшую цэну, чы то максімальная точнасць за будзь-яю цэну.
Зроўнасцаваная сістэма аналітыкі тэстуецца спецыяльным спосабам: зберагаюцца прыклады, выказваюцься чысткія тэзы, а таксама існуе цікл зворачнай связі, які перапісвае інструкцыі кожны раз, калі сістэма дапускае памылку. Databricks таксама выкорыстоўвае падобную ідэю у свайных дасягненнях Genie, якіе аб’едначаюць перагляд адпаведзей, крэтынгі, надзяйныя рэсурсы і структураваныя інструкцыі ў самы продукт.
У гэтым случае запыткі маюць меншое значэнне, чым прыметваюць людзі. Якосць заўсёды мае значэнне, але без сільнага семантычнага шару, застарэлых прыкладоў, зменных навыкаў і без ацэнак, жаданая запытка не зможа давяло вывучыць сістэму. Аналітыка агентав працюе тады, калі асоўнай сістэме паставляюцца стандарты дагляду, а не тады, калі модэлю даўаецца вольны доступ і яго заставляюць імпровізаваць.
Дзе команда з дадзенням можа пачаць
Найлепшы спосаб пачаць — з самай простой структуры, якая можа працаваць, практычна дадваючы складнасць толькі там, дзе рэзультаты пакажуць, што гэта корыстна. Кераванне Anthropic па стварэнні эфектываў агентав выражае тую ж думку, і яго пасляэтапныя аналізы падтрымліваюць яе. Ёсць пяць крокаў:
- Выберыце адну сферу, а не весь спектр задач, напрыклад, якосць доходаў, аператывныя працэсы падтрымкі, каналы росту або фінансавую звярненчасць. Выберыце сферу з чыярым адпаведальным і рэгулярнаючысяя запытаннямі.
Адно з таго, чаго трэба ухіліцца, — гэта падключэнне новейшага модэлю безпосерэдна да храніцы дадзэнняў і называнне гэтага падходу стратэгіяй. Такі падход навучае мало, акромя таго, як можа звучаць пераканальна неправільная адпаведзь.
Text-to-SQL займае адзін з месацоў для выканання задач у рамках такой парадыгмы. Проблема заключаецца ў тым, што гэта занадта простая канцэпцыя, каб опісаць цэлую сістэму. Гэта пытанне, верагодна, прыведзе да раздзелення команд на два групы: тых, хто спрыяе Text-to-SQL як самастоятны продукт, і тых, хто вважае яго часткай шырэйшага працэсу аналізу даных. Заслуговыя на увагу запітанні: звядзецца лярэстныя проблемы з чаго (неадкранасць, выкарыстоўванне некорэктных дадзеных, застарэласць інфармацыі чы слабкі працэс), чы ужо існуюць абавескі, неабходныя для працы агента з аналізу даных, чы праект не адкрое сябе ў скрытых проблемах мадэлі дадзеных, і што сёння включае слой навыкаў — чакамо падказкі, інструкцыі, прыклады SQL чы чэрніцы для аналітыкаў.
Дадатак: паўны шаблон навыкаў
Паўны шаблон навыкаў ад Anthropic прыведзены ніжэй.
---
name: [warehouse-skill]
version: [x.y.z]
description: "IF the user asks to query [the company]'s data warehouse for any
[list of business domains] question — THEN invoke this skill. DO NOT invoke
for [adjacent engineering tasks] or questions with no data-warehouse component."
---
# [Warehouse] Skill Instructions
## Description
The single source of truth for safe and effective [warehouse] querying.
Referenced by other skills [listed] for query execution guidance.
Act as a Data Analyst, providing strategic insights and data-driven
recommendations but seek guidance along the way.
**Out-of-scope decisions**: [product areas, etc.] → surface data only,
state "decision is [owning team]'s call", do NOT take a position or author
code fixes.
## Executing queries
Priority:
1. **[Managed connection]** (if available): [query tool] / [schema tool]
2. **[CLI fallback]** (if installed): [default project, fallback project]
3. **Neither** — ask the user to authenticate, then stop
---
# Semantic Layer (REQUIRED first step)
The governed semantic layer is the **mandatory default path** for every data
question — same numbers as [the BI tool], joins/grain/filters baked in. Raw SQL
via the reference docs below is the **fallback**, used only after the
semantic-layer path is shown not to cover the ask.
## Required workflow
1. **Load** — [how to load the semantic layer in each runtime, with fallbacks]
2. **Discover** — search measures/dimensions by keyword; **always check
segments** (the named canonical population filters — hand-rolled WHERE
clauses for these are the dominant wrong-answer mode)
3. **Compile + run** — build the spec → compile to SQL → execute
4. **Fallback** — only if discovery finds no relevant metric or compile fails
→ raw SQL via `references/*.md` (PART 3 below)
> **Don't bail early.** Do NOT fall back to raw SQL on these grounds:
> - "[custom date filtering / cohorts]" → [covered by time-dimension specs]
> - "[needs a join]" → [the metric layer already encapsulates its joins]
> - [3–4 more pre-rebutted excuses agents use to skip the semantic layer]
### Date windows & timezone — decide before you query
- **As-of date vs trailing-N days**: [convention for each]
- **"Last week/month"** → the last *complete* calendar week/month, not trailing-7/30
- **Timezone default**: [TZ]; [exception for certain reporting rollups]
- **Freshness lag**: [some] tables settle late — anchor on MAX(date), not "yesterday"
---
# PART 1: MUST KNOW (Read First for Every Request)
## 🚀 Quick Start Workflow
1. **Check for red flags first**: [restricted/PII requests, gated domains,
high-stakes asks that need extra validation]
2. **Out of scope — escalate, don't guess**: [access requests, pipeline
troubleshooting, stale dashboards, root-cause assertions, product/pricing
recommendations] → redirect to [the owning team], don't answer
3. **Clarify the request**: time period, segment, the business decision it informs
4. **Check for existing dashboards**: [per-domain dashboard catalogs]
5. **Identify the data source**: [navigation map below; prefer governed/aggregated tables]
6. **Execute the analysis**: [required filters + adversarial review]
7. **Deliver insights**: show methodology, differentiate observations from interpretations
## 🏢 Business Context
### Entity Disambiguation (MUST CLARIFY)
- **"[Term A]" can mean**: [entity 1] or [entity 2] — always clarify which
- **"[Term B]" can mean**: [entity 1] → [entity 2] → [entity 3] (one-to-many chain)
- **"Users"**: [which identifier gives accurate counts, and which ones inflate them]
### Business Terminology
- [Current product names vs deprecated aliases that still appear as frozen
values in the data layer — write with the new names, filter with the old]
- [Key internal acronyms]
- **[Headline metric] calculations**: [monthly / default window / leading indicator]
- **Unfamiliar terms — search [internal docs], don't guess**
### Data Integrity Requirements ⚠️
- **NEVER**: make up data/columns; make speculative assertions beyond what data shows
- **ALWAYS**: use safe division; differentiate observations ("data shows X")
from interpretations ("this suggests Y"); flag limitations
---
# PART 2: HOW TO DO (Follow During Execution)
## 🔧 Technical Execution Guide
- [Managed-connection tools and CLI invocation details]
- **PII protection**: for restricted data, return the SQL for the user to run
themselves — do not return results
## 📊 Analysis Best Practices Guide
1. Clarify the ask before querying
2. Show your work (filters, inclusions/exclusions, freshness)
3. Clarify denominators
4. Consider sample bias
5. Connect to business impact
6. **Adversarial SQL review (MANDATORY)** — spawn the [sql-reviewer] sub-agent
for every query before the final answer; blocking findings must be fixed
and re-reviewed; do not self-certify
7. **Report with provenance** — every answer ends with a footer:
> **Source:** [semantic layer | governed table | raw exploration] ·
> **Confidence:** [tier] · **Reviewed:** [reviewer ✓, round N] ·
> **Freshness:** [max date in the data] · **Owner:** [owning team]
---
# PART 3: DATA REFERENCES & RESOURCES
## 📚 Knowledge Base Navigation
### [Domain A] → `references/[domain_a].md`
- **Use for**: [kinds of questions]
- **Key tables**: [...]
- **Dashboards**: `references/[domain_a]_dashboards.json`
### [Domain B] → `references/[domain_b].md`
- **Use for**: [...]
[... one entry per business domain — a few dozen in total ...]
## ⚠️ Troubleshooting Guide
### When Information Is Missing
- [missing tables / access denied / outdated docs / unknown enum values → what to do]
### Field Naming Gotchas
- Use `[field_x_v2]` NOT `[field_x]`
- [Two similarly-named tables report the same metric at different grains — which to use]
- [Which of two plausible sources is canonical for the headline metric]
- [… a dozen more hard-won one-liners …]