Megosztás a következőn keresztül:

Utasítás-végrehajtási API: SQL futtatása a raktárakban

Fontos

A Databricks REST API-k eléréséhez hitelesítenie kell magát.

Ez az oktatóanyag bemutatja, hogyan futtathat SQL-utasításokat a Databricks SQL Warehouse-ból a Databricks SQL Statement Execution API 2.0 használatával.

A Databricks SQL Statement Execution API 2.0-ra vonatkozó hivatkozásának megtekintéséhez tekintse meg az Utasítás végrehajtása című témakört.

Mielőtt elkezdené

Mielőtt elkezdené ezt az oktatóanyagot, győződjön meg arról, hogy rendelkezik az alábbiakval:

  • A Databricks CLI 0.205-ös vagy újabb verziója, vagy curl az alábbiak szerint:

    • A Databricks CLI egy parancssori eszköz a Databricks REST API-kérések és -válaszok küldéséhez és fogadásához. Ha a Databricks CLI 0.205-ös vagy újabb verzióját használja, azt konfigurálni kell az Azure Databricks-munkaterület hitelesítéséhez. Lásd a Databricks parancssori felület telepítését vagy frissítését és a Databricks parancssori felület hitelesítését.

      Ha például a Databricks személyes hozzáférési jogkivonat-hitelesítésével szeretne hitelesíteni, kövesse a munkaterület-felhasználók személyes hozzáférési jogkivonatainak létrehozása című szakasz lépéseit.

      Ezután a Databricks parancssori felületének használatával hozzon létre egy Azure Databricks-konfigurációs profilt a személyes hozzáférési jogkivonathoz, tegye a következőket:

      Feljegyzés

      Az alábbi eljárás a Databricks CLI használatával hoz létre egy Azure Databricks-konfigurációs profilt a névvel DEFAULT. Ha már rendelkezik konfigurációs profillal DEFAULT , ez az eljárás felülírja a meglévő DEFAULT konfigurációs profilt.

      Annak ellenőrzéséhez, hogy már rendelkezik-e DEFAULT konfigurációs profillal, és a profil beállításainak megtekintéséhez, ha létezik, használja a Databricks parancssori felületet a databricks auth env --profile DEFAULT parancs futtatásához.

      Ahhoz, hogy konfigurációs profilt hozzon létre más néven, mint DEFAULT, a következő DEFAULT parancsban cserélje ki a --profile DEFAULT részének databricks configure-ját egy új névre a konfigurációs profil számára.

      1. A Databricks CLI használatával hozzon létre egy Azure Databricks-konfigurációs profiltDEFAULT, amely azure Databricks személyes hozzáférési jogkivonat-hitelesítést használ. Ehhez futtassa az alábbi parancsot:

        databricks configure --profile DEFAULT

      2. A következő Databricks Host mezőbe írja be az Azure Databricks munkaterületenkénti URL-címét, például https://adb-1234567890123456.7.azuredatabricks.net.

      3. A személyes hozzáférési jogkivonat megadásakor adja meg a munkaterülethez tartozó Azure Databricks személyes hozzáférési jogkivonatát.

      Az oktatóanyag Databricks CLI-példáiban jegyezze fel a következőket:

      • Ez az oktatóanyag feltételezi, hogy rendelkezik egy környezeti változóval DATABRICKS_SQL_WAREHOUSE_ID a helyi fejlesztőgépen. Ez a környezeti változó a Databricks SQL Warehouse azonosítóját jelöli. Az azonosító a raktár HTTP-elérési útjának mezőjében található /sql/1.0/warehouses/ után következő betűk és számok sztringje. A raktár HTTP-elérésiút-értékének lekéréséről az Azure Databricks számítási erőforrás kapcsolati adatainak lekérése című témakörben olvashat.
      • Ha a Windows parancssori héját használja a Unix, Linux vagy macOS parancshéj helyett, cserélje le \-t ^-re, és cserélje le ${...}-t %...%-ra.
      • Ha a Windows command shellt használja a Unix, Linux vagy macOS parancshéj helyett, a JSON-dokumentumdeklarációkban cserélje a nyitó és záró ' címkéket "-re, míg a belső " címkét cserélje \"-ra.

    • A curl egy parancssori eszköz REST API-kérések és válaszok küldéséhez és fogadásához. Lásd még : Install curl. Vagy adaptálhatja az oktatóanyag példáit curl hasonló eszközökkel, például a HTTPie-vel való használatra.

      A jelen oktatóanyag curl példáiban vegye észre a következőket:

      • --header "Authorization: Bearer ${DATABRICKS_TOKEN}"Ehelyett .netrc-fájlt használhat. Ha .netrc fájlt használ, cserélje le --header "Authorization: Bearer ${DATABRICKS_TOKEN}"-t --netrc-re.
      • Ha a Windows parancssori héját használja a Unix, Linux vagy macOS parancshéj helyett, cserélje le \-t ^-re, és cserélje le ${...}-t %...%-ra.
      • Ha a Windows command shellt használja a Unix, Linux vagy macOS parancshéj helyett, a JSON-dokumentumdeklarációkban cserélje a nyitó és záró ' címkéket "-re, míg a belső " címkét cserélje \"-ra.

      Az oktatóanyag példáihoz curl az alábbi környezeti változókat feltételezi a helyi fejlesztőgépen:

      • DATABRICKS_HOST, amely például az Azure Databricks-munkaterület munkaterületének nevétadb-1234567890123456.7.azuredatabricks.net jelöli.
      • DATABRICKS_TOKEN, amely egy Azure Databricks személyes hozzáférési jogkivonatot jelöl az Azure Databricks-munkaterület felhasználója számára.
      • DATABRICKS_SQL_WAREHOUSE_ID, amely a Databricks SQL Warehouse azonosítóját jelöli. Az azonosító a raktár HTTP-elérési útjának mezőjében található /sql/1.0/warehouses/ után következő betűk és számok sztringje. A raktár HTTP-elérésiút-értékének lekéréséről az Azure Databricks számítási erőforrás kapcsolati adatainak lekérése című témakörben olvashat.

      Feljegyzés

      Ajánlott biztonsági eljárásként, ha automatizált eszközökkel, rendszerekkel, szkriptekkel és alkalmazásokkal hitelesít, a Databricks azt javasolja, hogy munkaterület-felhasználók helyett a szolgáltatásnevekhez tartozó személyes hozzáférési jogkivonatokat használja. A szolgáltatásnevek jogkivonatainak létrehozásáról a szolgáltatásnév jogkivonatainak kezelése című témakörben olvashat.

      Az Azure Databricks személyes hozzáférési jogkivonatának létrehozásához kövesse a munkaterület-felhasználók személyes hozzáférési jogkivonatainak létrehozása című szakaszt.

      Figyelmeztetés

      A Databricks határozottan visszatartja a szkriptekbe való kemény kódolást, mivel ezek a bizalmas információk egyszerű szövegben, verziókövetési rendszereken keresztül is közzétehetők. A Databricks azt javasolja, hogy olyan megközelítéseket használjon, mint például a fejlesztői gépen beállított környezeti változók. Ha eltávolítja az ilyen szigorúan kódolt adatokat a szkriptekből, az segít, hogy ezek a szkriptek hordozhatóbbak legyenek.

  • Ez az oktatóanyag feltételezi, hogy rendelkezik a jq parancssori processzorral a JSON-válaszok lekérdezéséhez, amelyeket a Databricks SQL Statement Execution API minden egyes hívás után visszaad. Lásd: Letöltés jq.

  • Rendelkeznie kell legalább egy táblával, amellyel SQL-utasításokat hajthat végre. Ez az oktatóanyag a lineitem táblán alapul, amely a tpch sémában (más néven adatbázis) található a samples katalóguson belül. Ha nem fér hozzá ehhez a katalógushoz, sémához vagy táblához a munkaterületről, cserélje le őket az oktatóanyag során a sajátjával.

1. lépés: SQL-utasítás végrehajtása és az adateredmény mentése JSON-ként

Futtassa a következő parancsot, amely a következőket hajtja végre:

  1. A megadott SQL Warehouse-t és (ha használja) a megadott jogkivonatot használva, lekérdezi a curl katalógus lineitem sémájában lévő tcph tábla első két sorának három oszlopát.
  2. A válasz hasznos adatait JSON formátumban menti az aktuális munkakönyvtárban elnevezett sql-execution-response.json fájlba.
  3. Kinyomtatja a fájl tartalmát sql-execution-response.json .
  4. Beállít egy helyi környezeti változót .SQL_STATEMENT_ID Ez a változó a megfelelő SQL-utasítás azonosítóját tartalmazza. Ezt az SQL-utasításazonosítót használhatja az utasítással kapcsolatos információk igény szerinti lekéréséhez, amelyet a 2. lépés mutat be. Ezt az SQL-utasítást a Databricks SQL-konzol lekérdezéselőzmények szakaszából vagy a Lekérdezéselőzmények API meghívásával is megtekintheti és lekérheti annak utasításazonosítóját.
  5. Beállít egy további helyi környezeti változót, NEXT_CHUNK_EXTERNAL_LINK amely egy API URL-töredékét tartalmazza a JSON-adatok következő adattömbjének lekéréséhez. Ha a válaszadatok túl nagyok, a Databricks SQL Statement Execution API adattömbökben adja meg a választ. Ezt az API URL-töredékét használhatja a következő adattömb lekéréséhez, amelyet a 2. lépés mutat be. Ha nincs következő adattömb, akkor ez a környezeti változó a következőre nullvan állítva.
  6. Kinyomtatja a SQL_STATEMENT_ID és a NEXT_CHUNK_INTERNAL_LINK környezeti változók értékeit.

A Databricks parancssori felülete

databricks api post /api/2.0/sql/statements \
--profile <profile-name> \
--json '{
  "warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
  "catalog": "samples",
  "schema": "tpch",
  "statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
  "parameters": [
    { "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
    { "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
    { "name": "row_limit", "value": "2", "type": "INT" }
  ]
}' \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

Cserélje le <profile-name> az Azure Databricks-konfigurációs profil nevére a hitelesítéshez.

csavarodik

curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/ \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
  "warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
  "catalog": "samples",
  "schema": "tpch",
  "statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
  "parameters": [
    { "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
    { "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
    { "name": "row_limit", "value": "2", "type": "INT" }
  ]
}' \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

Az előző kérelemben:

  • A paraméteres lekérdezésekben minden paraméter neve elé egy kettőspont kerül (például: :extended_price), amely megfelelő name és value objektumként szerepel a parameters tömbben. Egy opcionális type is megadható, ellenkező esetben az alapértelmezett érték STRING lesz.

    Figyelmeztetés

    A Databricks határozottan javasolja, hogy az SQL-utasításokhoz ajánlott eljárásként használja a paramétereket.

    Ha a Databricks SQL Statement Execution API-t olyan alkalmazással használja, amely dinamikusan generálja az SQL-t, ez SQL-injektálási támadásokat eredményezhet. Ha például sql-kódot hoz létre a felhasználói felületen a felhasználó kijelölései alapján, és nem tesz megfelelő intézkedéseket, a támadó rosszindulatú SQL-kódot szúrhat be a kezdeti lekérdezés logikájának módosításához, ezáltal bizalmas adatok olvasásához, módosításához vagy törléséhez.

    A paraméteres lekérdezések segítenek megvédeni az SQL-injektálási támadásokat azáltal, hogy a bemeneti argumentumokat a többi SQL-kódtól elkülönítve kezelik, és ezeket az argumentumokat literális értékekként értelmezik. A paraméterek a kód újrafelhasználhatóságában is segítenek.

  • Alapértelmezés szerint a visszaadott adatok JSON-tömbformátumban vannak, és az SQL-utasítás adateredményeinek alapértelmezett helye a válasz hasznos adatai között van. Annak érdekében, hogy egyértelművé tegye ezt a viselkedést, adja hozzá a "format":"JSON_ARRAY","disposition":"INLINE"-t a kérelem hasznos teheréhez. Ha 25 MiB-nél nagyobb adateredményt próbál visszaadni a válasz terhelésében, a rendszer hibaállapotot jelez, és az SQL-utasítás megszakad. A 25 MiB-nél nagyobb adateredmények esetén külső hivatkozásokat használhat ahelyett, hogy megpróbálná visszaadni a válasz payloadjában, amelyet lásd a 3. lépésben.

  • A parancs a válasz hasznos adatainak tartalmát egy helyi fájlban tárolja. A Databricks SQL Statement Execution API közvetlenül nem támogatja a helyi adattárolást.

  • Alapértelmezés szerint 10 másodperc elteltével, ha az SQL-utasítás még nem fejezte be a végrehajtást a raktáron keresztül, a Databricks SQL Statement Execution API az utasítás eredménye helyett csak az SQL-utasítás azonosítóját és aktuális állapotát adja vissza. Ennek a viselkedésnek a megváltoztatásához adja hozzá "wait_timeout" a kéréshez, és állítsa be "<x>s" értékre, ahol <x>5 és 50 másodperc között lehet, például "50s". Az SQL-utasítás azonosítójának és aktuális állapotának azonnali visszaadásához állítsa be a következőt wait_timeout0s: .

  • Alapértelmezés szerint az SQL-utasítás továbbra is fut, ha eléri az időtúllépési időszakot. Ha az időkorlát elérkezik, és meg szeretné szüntetni az SQL-utasítást, adja hozzá a "on_wait_timeout":"CANCEL" elemet a kérelem törzséhez.

  • A visszaadott bájtok számának korlátozásához adja hozzá "byte_limit" a kéréshez, és állítsa be például 1000a bájtok számát.

  • A visszaadott sorok számának korlátozásához záradék LIMIThozzáadása statement helyett hozzáadhatja "row_limit" a kéréshez, és beállíthatja például "statement":"SELECT * FROM lineitem","row_limit":2a sorok számát.

  • Ha az eredmény nagyobb, mint a megadott byte_limit vagy row_limit, akkor a truncated mezőt true-re állítják a válaszban.

Ha az utasítás eredménye a várakozási időtúllépés vége előtt elérhetővé válik, a válasz a következő:

{
  "manifest": {
    "chunks": [
      {
        "chunk_index": 0,
        "row_count": 2,
        "row_offset": 0
      }
    ],
    "format": "JSON_ARRAY",
    "schema": {
      "column_count": 3,
      "columns": [
        {
          "name": "l_orderkey",
          "position": 0,
          "type_name": "LONG",
          "type_text": "BIGINT"
        },
        {
          "name": "l_extendedprice",
          "position": 1,
          "type_name": "DECIMAL",
          "type_precision": 18,
          "type_scale": 2,
          "type_text": "DECIMAL(18,2)"
        },
        {
          "name": "l_shipdate",
          "position": 2,
          "type_name": "DATE",
          "type_text": "DATE"
        }
      ]
    },
    "total_chunk_count": 1,
    "total_row_count": 2,
    "truncated": false
  },
  "result": {
    "chunk_index": 0,
    "data_array": [
      ["2", "71433.16", "1997-01-28"],
      ["7", "86152.02", "1996-01-15"]
    ],
    "row_count": 2,
    "row_offset": 0
  },
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "SUCCEEDED"
  }
}

Ha a várakozási időtúllépés az utasítás eredményének megjelenése előtt véget ér, a válasz a következőképpen néz ki:

{
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "PENDING"
  }
}

Ha az utasítás eredményadatai túl nagyok (például ebben az esetben futtatáskor SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000), az eredményadatok adattömbbe kerülnek, és így néznek ki. Vegye figyelembe, hogy itt a "...": "..." a rövidség kedvéért kihagyott eredményeket jelzi.

{
  "manifest": {
    "chunks": [
      {
        "chunk_index": 0,
        "row_count": 188416,
        "row_offset": 0
      },
      {
        "chunk_index": 1,
        "row_count": 111584,
        "row_offset": 188416
      }
    ],
    "format": "JSON_ARRAY",
    "schema": {
      "column_count": 3,
      "columns": [
        {
          "...": "..."
        }
      ]
    },
    "total_chunk_count": 2,
    "total_row_count": 300000,
    "truncated": false
  },
  "result": {
    "chunk_index": 0,
    "data_array": [["2", "71433.16", "1997-01-28"], ["..."]],
    "next_chunk_index": 1,
    "next_chunk_internal_link": "/api/2.0/sql/statements/00000000-0000-0000-0000-000000000000/result/chunks/1?row_offset=188416",
    "row_count": 188416,
    "row_offset": 0
  },
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "SUCCEEDED"
  }
}

2. lépés: Az utasítás aktuális végrehajtási állapotának és adateredményének lekérése JSON-ként

Az SQL-utasítás azonosítójával lekérheti az utasítás aktuális végrehajtási állapotát, és ha a végrehajtás sikeres volt, az utasítás eredménye. Ha elfelejti az utasítás azonosítóját, lekérheti a Databricks SQL-konzol lekérdezéselőzmények szakaszából vagy a Lekérdezéselőzmények API meghívásával. Például továbbra is lekérdezheti ezt a parancsot, és minden alkalommal ellenőrizheti, hogy a végrehajtás sikeres volt-e.

Az SQL-utasítás aktuális végrehajtási állapotának lekéréséhez és ha a végrehajtás sikeres volt, futtassa az alábbi parancsot az utasítás eredményének és egy API URL-töredékének lekéréséhez. Ez a parancs feltételezi, hogy rendelkezik egy környezeti változóval SQL_STATEMENT_IDa helyi fejlesztőgépen, amely az előző lépésben megadott SQL-utasítás azonosítójának értékére van beállítva. Az alábbi parancsot természetesen helyettesítheti ${SQL_STATEMENT_ID} az SQL-utasítás kódolt azonosítójával.

A Databricks parancssori felülete

databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

Cserélje le <profile-name> az Azure Databricks-konfigurációs profil nevére a hitelesítéshez.

csavarodik

curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

Ha az NEXT_CHUNK_INTERNAL_LINK érték nemnull értékre van állítva, akkor a következő adattömb lekérésére használható, és így tovább, például a következő paranccsal:

A Databricks parancssori felülete

databricks api get /${NEXT_CHUNK_INTERNAL_LINK} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

Cserélje le <profile-name> az Azure Databricks-konfigurációs profil nevére a hitelesítéshez.

csavarodik

curl --request GET \
https://${DATABRICKS_HOST}${NEXT_CHUNK_INTERNAL_LINK} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

Az előző parancsot újra és újra futtathatja a következő adattömb lekéréséhez, és így tovább. Vegye figyelembe, hogy az utolsó adattömb lekérése után az SQL-utasítás bezárul. A lezárás után nem használhatja az utasítás azonosítóját az aktuális állapot lekéréséhez vagy további adattömbök lekéréséhez.

Ez a szakasz egy választható konfigurációt mutat be, amely a nagy adatkészletek lekérésére használja a EXTERNAL_LINKS diszpozíciót. Az SQL-utasítás eredményadatainak alapértelmezett helye (eloszlása) a válasz hasznos adatain belül van, de ezek az eredmények legfeljebb 25 MiB-re korlátozódnak. A dispositionEXTERNAL_LINKS beállításával a válasz URL-címeket tartalmaz, amelyekkel lekérheti az eredményadatok részeit szabványos HTTP-vel. Az URL-címek a munkaterület belső DBFS-ére mutatnak, ahol az eredménytömbök ideiglenesen tárolódnak.

Figyelmeztetés

A Databricks erősen ajánlja a diszpozíció által EXTERNAL_LINKS visszaadott URL-címek és tokenek védelmét.

A diszpozíció használatakor EXTERNAL_LINKS létrejön egy közös hozzáférésű jogosultságkód (SAS) URL-cím, amellyel közvetlenül az Azure Storage-ból töltheti le az eredményeket. Mivel egy rövid élettartamú SAS-jogkivonat van beágyazva ebbe az SAS URL-címbe, az SAS URL-címet és az SAS-jogkivonatot is védenie kell.

Mivel az SAS-URL-címek már beágyazott ideiglenes SAS-jogkivonatokkal vannak létrehozva, nem szabad fejlécet Authorization beállítania a letöltési kérelmekben.

A EXTERNAL_LINKS letiltás kérelemre letiltható egy támogatási eset létrehozásával.

Lásd még a biztonsági ajánlott eljárásokat.

Feljegyzés

Az adott SQL-utasításazonosítóhoz rendelt válasz terhelési adatok kimeneti formátumát és viselkedését nem lehet módosítani beállításuk után.

Ebben a módban az API lehetővé teszi, hogy az eredményadatokat JSON formátumban (), CSV formátumban (JSONCSV) vagy Apache Arrow formátumban (ARROW_STREAM) tárolja, amelyeket külön kell lekérdezni a HTTP-vel. Ha ezt a módot használja, az eredményadatok nem ágyazhatóak be a válasz hasznos adataiba.

Az alábbi parancs a EXTERNAL_LINKS és az Apache Arrow formátum használatát demonstrálja. Használja ezt a mintát az 1. lépésben bemutatott hasonló lekérdezés helyett:

A Databricks parancssori felülete

databricks api post /api/2.0/sql/statements/ \
--profile <profile-name> \
--json '{
  "warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
  "catalog": "samples",
  "schema": "tpch",
  "format": "ARROW_STREAM",
  "disposition": "EXTERNAL_LINKS",
  "statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
  "parameters": [
    { "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
    { "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
    { "name": "row_limit", "value": "100000", "type": "INT" }
  ]
}' \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID

Cserélje le <profile-name> az Azure Databricks-konfigurációs profil nevére a hitelesítéshez.

csavarodik

curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/ \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
  "warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
  "catalog": "samples",
  "schema": "tpch",
  "format": "ARROW_STREAM",
  "disposition": "EXTERNAL_LINKS",
  "statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
  "parameters": [
    { "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
    { "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
    { "name": "row_limit", "value": "100000", "type": "INT" }
  ]
}' \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID

A válasz a következő:

{
  "manifest": {
    "chunks": [
      {
        "byte_count": 2843848,
        "chunk_index": 0,
        "row_count": 100000,
        "row_offset": 0
      }
    ],
    "format": "ARROW_STREAM",
    "schema": {
      "column_count": 3,
      "columns": [
        {
          "name": "l_orderkey",
          "position": 0,
          "type_name": "LONG",
          "type_text": "BIGINT"
        },
        {
          "name": "l_extendedprice",
          "position": 1,
          "type_name": "DECIMAL",
          "type_precision": 18,
          "type_scale": 2,
          "type_text": "DECIMAL(18,2)"
        },
        {
          "name": "l_shipdate",
          "position": 2,
          "type_name": "DATE",
          "type_text": "DATE"
        }
      ]
    },
    "total_byte_count": 2843848,
    "total_chunk_count": 1,
    "total_row_count": 100000,
    "truncated": false
  },
  "result": {
    "external_links": [
      {
        "byte_count": 2843848,
        "chunk_index": 0,
        "expiration": "<url-expiration-timestamp>",
        "external_link": "<url-to-data-stored-externally>",
        "row_count": 100000,
        "row_offset": 0
      }
    ]
  },
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "SUCCEEDED"
  }
}

Ha a kérés túllépi az időkorlátot, a válasz a következőképpen néz ki:

{
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "PENDING"
  }
}

Az utasítás aktuális végrehajtási állapotának lekéréséhez és ha a végrehajtás sikeres volt, futtassa az alábbi parancsot:

A Databricks parancssori felülete

databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'

Cserélje le <profile-name> az Azure Databricks-konfigurációs profil nevére a hitelesítéshez.

csavarodik

curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'

Ha a válasz elég nagy (például ebben az esetben sorkorlát nélkül fut SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem ), a válasz több adattömbből áll, mint az alábbi példában. Vegye figyelembe, hogy itt a "...": "..." a rövidség kedvéért kihagyott eredményeket jelzi.

{
  "manifest": {
    "chunks": [
      {
        "byte_count": 11469280,
        "chunk_index": 0,
        "row_count": 403354,
        "row_offset": 0
      },
      {
        "byte_count": 6282464,
        "chunk_index": 1,
        "row_count": 220939,
        "row_offset": 403354
      },
      {
        "...": "..."
      },
      {
        "byte_count": 6322880,
        "chunk_index": 10,
        "row_count": 222355,
        "row_offset": 3113156
      }
    ],
    "format": "ARROW_STREAM",
    "schema": {
      "column_count": 3,
      "columns": [
        {
          "...": "..."
        }
      ]
    },
    "total_byte_count": 94845304,
    "total_chunk_count": 11,
    "total_row_count": 3335511,
    "truncated": false
  },
  "result": {
    "external_links": [
      {
        "byte_count": 11469280,
        "chunk_index": 0,
        "expiration": "<url-expiration-timestamp>",
        "external_link": "<url-to-data-stored-externally>",
        "next_chunk_index": 1,
        "next_chunk_internal_link": "/api/2.0/sql/statements/00000000-0000-0000-0000-000000000000/result/chunks/1?row_offset=403354",
        "row_count": 403354,
        "row_offset": 0
      }
    ]
  },
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "SUCCEEDED"
  }
}

A tárolt tartalom eredményeinek letöltéséhez futtassa az alábbi curl parancsot az objektum URL-címével external_link , és adja meg, hogy hol szeretné letölteni a fájlt. Ne foglalja bele az Azure Databricks-jogkivonatot ebbe a parancsba:

curl "<url-to-result-stored-externally>" \
--output "<path/to/download/the/file/locally>"

A streamelt tartalom eredményeinek egy adott adattömbjének letöltéséhez az alábbiak egyikét használhatja:

  • A next_chunk_index válasz hasznos adatainak értéke a következő adattömbhöz (ha van egy következő adattömb).
  • Ha több adattömb van, a válasz hasznos adatjegyzékéből származó adattömbindexek egyike a rendelkezésre álló adattömbökhöz.

Például, hogy megkapja a chunk_index10 részt az előző válaszból, futtassa a következő parancsot:

A Databricks parancssori felülete

databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID}/result/chunks/10 \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'

Cserélje le <profile-name> az Azure Databricks-konfigurációs profil nevére a hitelesítéshez.

csavarodik

curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/result/chunks/10 \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'

Feljegyzés

Az előző parancs futtatása egy új SAS URL-címet ad vissza.

A tárolt adattömb letöltéséhez használja az objektum URL-címét external_link .

További információ az Apache Arrow formátumról:

4. lépés: SQL-utasítás végrehajtásának megszakítása

Ha egy még nem sikeres SQL-utasítást kell visszavonnia, futtassa a következő parancsot:

A Databricks parancssori felülete

databricks api post /api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--profile <profile-name> \
--json '{}'

Cserélje le <profile-name> az Azure Databricks-konfigurációs profil nevére a hitelesítéshez.

csavarodik

curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"

Ajánlott biztonsági eljárások

A Databricks SQL Statement Execution API a végpontok közötti átvitel biztonsági (TLS) titkosításával és a rövid élettartamú hitelesítő adatokkal, például SAS-jogkivonatokkal növeli az adatátvitel biztonságát.

Ebben a biztonsági modellben több réteg is található. Az átviteli rétegben a Databricks SQL Statement Execution API meghívása csak TLS 1.2 vagy újabb használatával lehetséges. Emellett a Databricks SQL Statement Execution API hívóit hitelesíteni kell érvényes Azure Databricks személyes hozzáférési tokennel, OAuth hozzáférési tokennel vagy Microsoft Entra ID tokennel (korábbi nevén Azure Active Directory), amely hozzárendelődik egy olyan felhasználóhoz, aki jogosult a Databricks SQL használatára. Ennek a felhasználónak rendelkeznie kell használati joggal a használt SQL-tárházhoz, és a hozzáférés IP-hozzáférési listákkal korlátozható. Ez a Databricks SQL Statement Execution API-ra irányuló összes kérésre vonatkozik. Ezenkívül az utasítások végrehajtásához a hitelesített felhasználónak engedéllyel kell rendelkeznie az egyes utasításokban használt adatobjektumokhoz (például táblákhoz, nézetekhez és függvényekhez). Ezt a Unity Katalógus meglévő hozzáférés-vezérlési mechanizmusai vagy a tábla ACL-jei kényszerítik ki. (További részletekért tekintse meg az Azure Databricks adatszabályozását .) Ez azt is jelenti, hogy csak az utasítást végrehajtó felhasználó kérheti le az utasítás eredményeit.

A Databricks a következő ajánlott biztonsági eljárásokat javasolja a Databricks SQL Statement Execution API használatakor, valamint a EXTERNAL_LINKS nagyméretű adatkészletek lekérésére vonatkozó diszpozícióval együtt:

  • Az Azure Storage-kérelmek Databricks-engedélyezési fejlécének eltávolítása
  • SAS-URL-címek és SAS-jogkivonatok védelme

A EXTERNAL_LINKS letiltás kérelemre letiltható egy támogatási eset létrehozásával. A kérés teljesítéséhez forduljon az Azure Databricks-fiók csapatához.

Az Azure Storage-kérelmek Databricks-engedélyezési fejlécének eltávolítása

A Databricks SQL Utasítás végrehajtási API-jának minden olyan curl hívásának tartalmaznia kell egy Authorization fejlécet, amely tartalmazza az Azure Databricks hozzáférési hitelesítő adatait. Ne tartalmazza ezt a Authorization fejlécet, amikor adatokat tölt le az Azure Storage tárhelyről. Ez a fejléc nem szükséges, és előfordulhat, hogy véletlenül elérhetővé teszi az Azure Databricks hozzáférési hitelesítő adatait.

SAS-URL-címek és SAS-jogkivonatok védelme

A diszpozíció használatakor EXTERNAL_LINKS létrejön egy rövid élettartamú SAS URL-cím, amellyel a hívó közvetlenül az Azure Storage-ból töltheti le az eredményeket a TLS használatával. Mivel egy rövid élettartamú SAS-jogkivonat van beágyazva ebbe az SAS URL-címbe, az SAS URL-címet és az SAS-jogkivonatot is védenie kell.

  • Last updated on