Požadavek sql-query

Účel a dopady

Spustí jeden nebo více SQL příkazů SELECT nad databází a vrátí jejich výsledky jako XML. Požadavek sám o sobě nic nemění v databázi (jde výhradně o SELECT), ale svým průběhem ovlivňuje interní statistiku doby trvání dotazů.

Dostupnost, kontext, oprávnění apod.

• Dostupné každému přihlášenému uživateli; jednotlivé select se spouští pod databázovým loginem přiřazeným efektivní roli volajícího (role, případně přepsané atributem opt-roles), ne pod obecným systémovým účtem.
• Dotaz směrovaný do archivní databáze (archive="true") smí spustit jen uživatel s r_admin – jinak je zamítnut jako bezpečnostní chyba.
• Je-li na serveru zapnutý konfigurační filtr dotazů, je zamítnut i select, jehož text obsahuje master., model., tempdb., msdb., CONNECTIONPROPERTY(, SERVERPROPERTY( nebo @@.
• Podléhá standardnímu transakčnímu zpracování obálky <request> (transactional/přeskočení při odvolané transakci) – viz obálka požadavku.

XML požadavek (syntax + popis)

  <request>
   <sql-query
    archive="{bool}"
    opt-roles="{string}"
    >
    <select
     type="{string}"
     setting="{number}"
     user="{number}"
     opt-roles="{string}"
     archive="{bool}"
     avoid-xml="{bool}"
     measure-time="{bool}"
     >
     {string}
    </select> *
   </sql-query>
  </request>

Parametry a pravidla (atributy, potomci)

Uzel sql-query

• archive - Archivní databáze - Výchozí hodnota archive pro všechny vnořené select, které ji sami nepřepíšou. (typ: bool; nepovinný; výchozí: false)
• opt-roles - Volitelná role - Výchozí volitelná role pro všechny vnořené select, které ji sami nepřepíšou. (typ: string; nepovinný)

Potomek: select (0 a vícekrát).

Uzel select

Obsahuje text SQL příkazu SELECT. Uzel nemá další potomky.

• type - Typový název - Identifikace položky bez mezer a diakritiky (lze použít pomlčky a podtržítka); server ji beze změny přenáší do odpovídajícího uzlu result. (typ: string; nepovinný)
• setting - Setting id - Celočíselný identifikátor pro interní statistiku doby trvání dotazů; neplatná nebo chybějící hodnota se nahrazuje -1. (typ: number; nepovinný; výchozí: -1)
• user - Číslo uživatele - Stejný účel jako setting, součást klíče interní statistiky; neplatná nebo chybějící hodnota se nahrazuje -1. (typ: number; nepovinný; výchozí: -1)
• opt-roles - Volitelná role - Přepíše pro tento select roli zděděnou z sql-query/přihlášení. (typ: string; nepovinný)
• archive - Archivní databáze - Přepíše pro tento select hodnotu zděděnou z sql-query. Vyžaduje r_admin, jinak je select zamítnut. (typ: bool; nepovinný; výchozí: hodnota sql-query/@archive)
• avoid-xml - Bez automatického XML - Není-li "true", server ke skutečnému textu SELECTu automaticky připojí " FOR XML RAW". Text SELECTu proto sám FOR XML RAW obsahovat nemá – došlo by ke zdvojení a syntaktické chybě. (typ: bool; nepovinný; výchozí: false)
• measure-time - Měření doby trvání - Je-li "true", doplní se do odpovídajícího uzlu result atributy duration-query a duration-fetch. Stejný efekt může vyvolat i globální konfigurační příznak serveru. (typ: bool; nepovinný; výchozí: false)

Závislosti

• select/@archive (je-li uveden) přepisuje sql-query/@archive; bez uvedení platí hodnota zděděná z sql-query.
• select/@opt-roles (je-li uveden) přepisuje sql-query/@opt-roles; bez uvedení platí role přihlášeného uživatele nebo hodnota zděděná z sql-query.
• Text SELECTu obsahující řetězec -!- je serverem nahrazen číslem efektivní role volajícího – v archivním režimu (archive="true") je -!- nahrazen prázdným řetězcem místo čísla role. Typicky se používá pro dotazy nad view/objekty parametrizovanými rolí.

Vyhrazené kombinace type a textu SELECTu

Je-li type roven přesně "cycle-status", "xsystem____" nebo "getDate" a text SELECTu odpovídá jednomu z pěti pevně daných řetězců používaných pro synchronizaci času/cyklu, server dotaz vůbec nepředává databázi a vrací syntetickou odpověď. Mimo tuto přesnou shodu se select zpracuje běžným způsobem.

Příklady požadavku

(Zatím bez ověřeného příkladu; viz příklady dotazů a identifikace chyb.)

Zpracování a vedlejší účinky

• Ke skutečnému textu SELECTu se automaticky připojuje " FOR XML RAW" (pokud avoid-xml není "true") – uzel row v odpovědi je tedy přímým výstupem této klauzule MSSQL: co sloupec/alias v SELECTu, to atribut uzlu row.
• Selhání jednoho select ukončuje zpracování zbytku požadavku. Jakmile libovolný select v rámci sql-query selže (bezpečnostní filtr, chyba databáze, neplatná role), server přestane provádět všechny další select v tomtéž požadavku – ty se vůbec nespustí a v odpovědi pro ně nevznikne ani result, ani error. Klient nemá jak z odpovědi poznat, že pozdější select byl jen vynechán, a ne že vrátil prázdný výsledek.
• Atributy user a setting tvoří spolu s type klíč interní agregované statistiky doby trvání dotazů (průměr a součet čtverců doby dotazu i fetch fáze). Agregace se zapisuje jen tehdy, je-li na serveru globálně zapnuté měření doby trvání; samotné measure-time="true" na jednotlivém select do agregátu nezapisuje, jen vrací naměřené hodnoty v odpovědi.
• Prázdný text SELECTu (uzel select bez obsahu) je platný a vždy uspěje – vrátí <result type="…"/> bez volání databáze.

XML odpověď (syntax + popis)

  <response>
   <sql-query-result>
    <result
     type="{string}"
     duration-query="{number}"
     duration-fetch="{number}"
     >
     <row ... /> *
    </result> *
    <error ... /> *
   </sql-query-result>
  </response>

Příklady odpovědi

(Zatím bez ověřeného příkladu; viz příklady dotazů a identifikace chyb.)

Chyby a reakce

• Za každý úspěšně provedený select vzniká právě jeden uzel result se stejným type, jaký měl vstupní select (prázdný, pokud type nebyl uveden). Atributy duration-query/duration-fetch se doplní jen při measure-time="true" nebo zapnutém globálním měření doby trvání.
• Za neúspěšný select (bezpečnostní filtr nebo chyba databáze) nevzniká žádný result; místo něj se do odpovědi vloží jeden nebo více uzlů error (obecný tvar viz sdílený typ error) – databázová vrstva může k jedné chybě zalogovat víc diagnostických záznamů, takže error se může vyskytnout i vícekrát za jediný neúspěšný select.
• Jak je popsáno výše v sekci Zpracování, první neúspěch v dávce znamená, že se všechny následující select v tomtéž požadavku přeskočí beze stopy (bez result i bez error).
• Výraz pro identifikaci chyb v odpovědi serveru: sql-query-result[error].

Související požadavky

• get-settings, save-settings – další způsob práce s XML/SQL daty ve stejné skupině požadavků.