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

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 curlaz 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 CLI telepítése vagy update a Databricks CLI és hitelesítése a Databricks CLI-hez.

    Ha például a Databricks személyes hozzáférési jogkivonat-hitelesítésével szeretne hitelesíteni, kövesse az Azure Databricks személyes hozzáférési jogkivonatainak lépéseit a munkaterület felhasználói számára.

    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 rendelkezik-e DEFAULT már konfigurációs profillal, és ha létezik, tekintse meg a profil beállításait, a Databricks parancssori felületével futtassa a parancsot databricks auth env --profile DEFAULT.

    Ha nem más DEFAULTnéven szeretne konfigurációs profilt létrehozni, cserélje le a DEFAULT következő --profile DEFAULT parancs egy másik databricks configure nevére a konfigurációs profilt.

    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 databricks-gazdagép kéréséhez adja meg például az Azure Databricks https://adb-1234567890123456.7.azuredatabricks.net.

    3. A személyes hozzáférési jogkivonat megadásához adja meg a munkaterület 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. Ez az azonosító a raktár HTTP-elérési útjának/sql/1.0/warehouses/következő betűk és számok sztringje. További információért arról, hogyan a raktár HTTP elérési útjának értékét, tekintse meg az Azure Databricks számítási erőforrás kapcsolati adatait.
    • Ha a Windows command shellt használja a Unix, Linux vagy macOS parancshéj helyett, cserélje le \ a következőre ^, és cserélje le ${...} a következőre %...%: .
    • Ha a Windows command shellt használja a Unix, Linux vagy macOS parancshéj helyett, JSON-dokumentumdeklarációkban cserélje le a megnyitást és a befejezést '", és cserélje le a belsőt " a következőre \": .

  • 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.

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

    • --header "Authorization: Bearer ${DATABRICKS_TOKEN}"Ehelyett .netrc-fájlt használhat. Ha fájlt használ .netrc , cserélje le a következőre --header "Authorization: Bearer ${DATABRICKS_TOKEN}"--netrc: .
    • Ha a Windows command shellt használja a Unix, Linux vagy macOS parancshéj helyett, cserélje le \ a következőre ^, és cserélje le ${...} a következőre %...%: .
    • Ha a Windows command shellt használja a Unix, Linux vagy macOS parancshéj helyett, JSON-dokumentumdeklarációkban cserélje le a megnyitást és a befejezést '", és cserélje le a belsőt " a következőre \": .

    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. Ez az azonosító a raktár HTTP-elérési útjának/sql/1.0/warehouses/következő betűk és számok sztringje. Annak érdekében, hogy megtudja, hogyan állíthatja be a raktára HTTP-útvonalának értékét , tekintse meg azAzure Databricks számítási erőforrás kapcsolati adatait.

    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 az Azure Databricks személyes hozzáférési jogkivonatait a munkaterület-felhasználók számára.

    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 set 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 a JQ parancssori processzorral is rendelkezik a JSON-válasz hasznos adatainak lekérdezéséhez, amelyet a Databricks SQL Statement Execution API a Databricks SQL-utasítás végrehajtási API-jának minden egyes hívása után visszaad. Lásd: Letöltés jq.

• Rendelkeznie kell legalább egy table, amellyel SQL-utasításokat hajthat végre. Ez az oktatóanyag a lineitemtable alapul a tpchschema-ban (más néven adatbázis) a samplescatalog-en belül. Ha nem fér hozzá ehhez a catalog, schemavagy table a munkaterületről, cserélje le őket az oktatóanyag során a saját helyére.

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. Használja a megadott SQL Warehouse-t és, ha a curl-t használja, a megadott jogkivonatot is, hogy lekérdezzen három columns-t a samplescatalogtcphschemalineitemtable első két sorából.
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 is megtekintheti és get annak utasításazonosítóját, vagy meghívhatja a Lekérdezéselőzmények API-.
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ó setnull.
6. A(z) values értékét nyomtatja ki a SQL_STATEMENT_ID és NEXT_CHUNK_INTERNAL_LINK környezeti változók alapján.

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ések minden lekérdezési paraméter nevét kettősponttal (például ) előzik meg, :extended_priceamely egyező name és value egy objektumot tartalmaz a parameters tömbben. Megadható opcionális type is, ha nincs megadva az alapértelmezett érték STRING .

  Figyelmeztetés

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

  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 generate SQL-kódot egy felhasználói felületen megadott beállítások 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 valuesértelmezik. Parameters a kód újrafelhasználhatóságát is segíti.

• 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. A viselkedés explicitvá tétele érdekében adja hozzá "format":"JSON_ARRAY","disposition":"INLINE" a kérelem hasznos adatait. Ha 25 MiB-nél nagyobb adateredményeket próbál visszaadni a válasz hasznos adataiban, a rendszer hibaállapotot ad vissza, é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 hasznos adataiban, amelyet a 3. lépés mutat be.

• 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. A viselkedés módosításához adja hozzá a "wait_timeout" elemet a kéréshez, és set a(z) "<x>s"-hez. A where<x> az 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 setwait_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őtúllépési időszak elérésekor meg szeretné szüntetni az SQL-utasítást, adja hozzá "on_wait_timeout":"CANCEL" a kérelem hasznos adatait.

• A visszaadott bájtok számának limit adja hozzá a kéréshez "byte_limit", és set a bájtok számához, például 1000.

• Ha limit a visszaadott sorok számát, ahelyett, hogy hozzáadna egy LIMIT záradékot a(z) statement-hez, hozzáadhat "row_limit" a kéréshez és set a sorok számához, például "statement":"SELECT * FROM lineitem","row_limit":2esetén.

• Ha az eredmény nagyobb, mint a megadott byte_limit vagy row_limit, a truncated mező settrue a válasz hasznos adataiban.

Ha az utasítás eredménye a várakozási időtúllépés vége előtt érhető el, 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. Figyelje meg, hogy itt "...": "..." nem található eredmény a rövidség kedvéért:

{
  "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: egy utasítás aktuális végrehajtási állapotának és adateredményének JSON formátumú Get fájlként történő lekérése

Az SQL-utasítás azonosítójával get 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, a Databricks SQL-konzol lekérdezési előzményeiről, vagy a Lekérdezéselőzmények APImeghí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.

Ha get egy SQL-utasítás aktuális végrehajtási állapotát, é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 a helyi fejlesztőgépen SQL_STATEMENT_IDnevű környezeti változó található, amely set az előző lépésben szereplő SQL-utasítás azonosítójának értékéhez. 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 a NEXT_CHUNK_INTERNAL_LINK nemnull értékre set, a következő adattömb get, é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 get, é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 get vagy további adattömbök beolvasására.

3. lépés: Nagy eredmények lekérése külső hivatkozások használatával

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 beállítással a dispositionEXTERNAL_LINKSválasz URL-címeket tartalmaz, amellyel lekérheti az eredményadatok adattömbjeit a szabványos HTTP-vel. Az URL-címek a munkaterület belső DBFS-ére mutatnak, where az eredménytömbök ideiglenesen tárolódnak.

Az alábbi parancs a használatot EXTERNAL_LINKS és az Apache Arrow formátumot mutatja be. 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"
  }
}

A get az utasítás aktuális végrehajtási állapotát, és ha a végrehajtás sikeres volt, az utasítás eredményét, 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 SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem sor nélküli limitfuttatásával), a válasz több adattömbből áll, mint az alábbi példában. Figyelje meg, hogy itt "...": "..." nem található eredmény a rövidség kedvéért:

{
  "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 a external_link objektum URL-címével, és adja meg a fájlt letölteni kívánt where. 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.

Ha például az előző válaszból származó 10chunk_indexget, 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'

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:

• IPC streaming formátuma
• Streamelési formátum írása és olvasása
• Streamek használata

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 átviteli rétegbeli titkosítás (TLS) titkosításával és a rövid élettartamú credentials, 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 jogkivonattal, OAuth hozzáférési jogkivonattal vagy Microsoft Entra-azonosítóval (korábbi nevén Azure Active Directory) olyan felhasználóhoz, aki jogosult a Databricks SQL használatára. Ennek a felhasználónak rendelkeznie kell a használt SQL-tárolóhoz való HOZZÁFÉRÉSsel, é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 tables, viewsés függvényekhez). Ezt a Unity Catalog meglévő hozzáférés-vezérlési mechanizmusai vagy table ACL-ek használatával kényszerítik ki. (További részletekért tekintse meg a Unity Catalog 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:

• Remove Az Azure Storage-kérelmekhez tartozó Databricks-engedélyezési fejléc
• 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.

Remove Az Azure-tárolási kérelmekhez tartozó Databricks engedélyezési fejléc

Az curl használó Databricks SQL Statement Execution API-ra irányuló összes hívásnak tartalmaznia kell egy Authorization fejlécet, amely tartalmazza az Azure Databricks hozzáférési credentials. Ne adja meg ezt a Authorization fejlécet, amikor adatokat tölt le az Azure Storage-ból. Ez a fejléc nem szükséges, és véletlenül elérhetővé teheti az Azure Databricks hozzáférését credentials.

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.