Synapse SQL 内で SQL オンデマンド (プレビュー) リソースを使用してストレージ ファイルに対してクエリを実行するQuery storage files using SQL on-demand (preview) resources within Synapse SQL

SQL オンデマンド (プレビュー) を使用すると、データ レイク内のデータに対してクエリを実行できます。SQL on-demand (preview) enables you to query data in your data lake. これには、半構造化と非構造化のデータのクエリに対応する T-SQL クエリ領域が用意されています。It offers a T-SQL query surface area that accommodates semi-structured and unstructured data queries. クエリでは、次の T-SQL の側面がサポートされています。For querying, the following T-SQL aspects are supported:

現在サポートされているものとされていないものの詳細については、SQL オンデマンドの概要に関する記事、または以下の記事をご覧ください。For more information on what is vs. what isn't currently supported, read the SQL on-demand overview article, or the following articles:

概要Overview

Azure Storage ファイルに格納されているデータに対するインプレース クエリのスムーズな実行をサポートするために、SQL オンデマンドでは、次の追加機能を持つ OPENROWSET 関数が使用されます。To support a smooth experience for in place querying of data that's located in Azure Storage files, SQL on-demand uses the OPENROWSET function with additional capabilities:

PARQUET ファイルに対してクエリを実行するQuery PARQUET files

Parquet ソース データに対してクエリを実行するには、FORMAT = 'PARQUET' を使用します。To query Parquet source data, use FORMAT = 'PARQUET'

SELECT * FROM
OPENROWSET( BULK N'https://myaccount.dfs.core.windows.net//mycontainer/mysubfolder/data.parquet', FORMAT = 'PARQUET') 
WITH (C1 int, C2 varchar(20), C3 as varchar(max)) as rows

使用例については、Parquet ファイルに対するクエリの実行に関する記事を参照してください。Review the Query Parquet files article for usage examples.

CSV ファイルに対してクエリを実行するQuery CSV files

CSV ソース データに対してクエリを実行するには、FORMAT = 'CSV' を使用します。To query CSV source data, use FORMAT = 'CSV'. CSV ファイルに対してクエリを実行するときに、OPENROWSET 関数の一部として CSV ファイルのスキーマを指定できます。You can specify schema of the CSV file as part of OPENROWSET function when you query CSV files:

SELECT * FROM
OPENROWSET( BULK N'https://myaccount.dfs.core.windows.net/mycontainer/mysubfolder/data.csv', FORMAT = 'CSV', PARSER_VERSION='2.0') 
WITH (C1 int, C2 varchar(20), C3 as varchar(max)) as rows

解析規則をカスタム CSV 形式に合わせて調整するために使用できる追加オプションがいくつかあります。There are some additional options that can be used to adjust parsing rules to custom CSv format:

  • ESCAPE_CHAR = 'char' は、ファイル内でそれ自体とすべての区切り記号の値をエスケープするために使用するファイル内の文字を指定します。ESCAPE_CHAR = 'char' Specifies the character in the file that is used to escape itself and all delimiter values in the file. エスケープ文字の後にそれ自体以外の値、またはいずれかの区切り記号の値が続く場合は、その値を読み取るときにエスケープ文字が削除されます。If the escape character is followed by a value other than itself, or any of the delimiter values, the escape character is dropped when reading the value. ESCAPE_CHAR パラメーターは、FIELDQUOTE が有効かどうかに関係なく適用されます。The ESCAPE_CHAR parameter will be applied whether the FIELDQUOTE is or isn't enabled. 引用文字をエスケープするために使用されることはありません。It won't be used to escape the quoting character. 引用文字は、別の引用文字でエスケープする必要があります。The quoting character must be escaped with another quoting character. 引用文字は、値が引用文字で囲まれている場合にのみ、列の値の中で使用できます。Quoting character can appear within column value only if value is encapsulated with quoting characters.
  • FIELDTERMINATOR ='field_terminator' は、使用するフィールド ターミネータを指定します。FIELDTERMINATOR ='field_terminator' Specifies the field terminator to be used. 既定のフィールド ターミネータはコンマ (" , ") です。The default field terminator is a comma (",")
  • ROWTERMINATOR ='row_terminator' は、使用する行ターミネータを指定します。ROWTERMINATOR ='row_terminator' Specifies the row terminator to be used. 既定の行ターミネータは、改行文字  \r\n です。The default row terminator is a newline character: \r\n.

ファイル スキーマFile schema

Synapse SQL の SQL 言語を使用すると、ファイルのスキーマを OPENROWSET 関数の一部として定義し、列のすべてまたはサブセットを読み取ることができます。また、スキーマの推論を使用して、ファイルから列の型を自動的に決定することもできます。SQL language in Synapse SQL enables you to define schema of the file as part of OPENROWSET function and read all or subset of columns, or it tries to automatically determine column types from the file using schema inference.

選択した列のサブセットを読み取るRead a chosen subset of columns

読み取る列を指定するには、OPENROWSET ステートメント内にオプションの WITH 句を指定できます。To specify columns that you want to read, you can provide an optional WITH clause within your OPENROWSET statement.

  • CSV データ ファイルがある場合、すべての列を読み取るには、列名とそのデータ型を指定します。If there are CSV data files, to read all the columns, provide column names and their data types. 列のサブセットが必要な場合は、序数を使用して、元のデータ ファイルから序数で列を選択します。If you want a subset of columns, use ordinal numbers to pick the columns from the originating data files by ordinal. 列は、序数の指定によってバインドされます。Columns will be bound by the ordinal designation.
  • Parquet データ ファイルがある場合は、元のデータ ファイル内の列名と一致する列名を指定します。If there are Parquet data files, provide column names that match the column names in the originating data files. 列は名前によってバインドされます。Columns will be bound by name.
SELECT * FROM
OPENROWSET( BULK N'https://myaccount.dfs.core.windows.net/mycontainer/mysubfolder/data.parquet', FORMAT = 'PARQUET') 
WITH (
      C1 int, 
      C2 varchar(20),
      C3 as varchar(max)
) as rows

列ごとに、列の名前と型を WITH 句で指定する必要があります。For every column, you need to specify column name and type in WITH clause. サンプルについては、すべての列を指定せずに CSV ファイルを読み取ることに関する記事を参照してください。For samples, refer to Read CSV files without specifying all columns.

スキーマ推論Schema inference

OPENROWSET ステートメントから WITH 句を省略することで、基になるファイルからスキーマを自動検出 (推論) するようにサービスに指示できます。By omitting the WITH clause from the OPENROWSET statement, you can instruct the service to auto detect (infer) the schema from underlying files.

注意

これは現在、PARQUET ファイル形式でのみ機能します。This currently works only for PARQUET file format.

SELECT * FROM
OPENROWSET( BULK N'https://myaccount.dfs.core.windows.net/mycontainer/mysubfolder/data.parquet', FORMAT = 'PARQUET') 

最適なパフォーマンスが得られる適切な推定データ型が使用されていることを確認してください。Make sure appropriate inferred data types are used for optimal performance.

複数のファイルまたはフォルダーに対してクエリを実行するQuery multiple files or folders

1 つのフォルダーまたは一連のフォルダー内にある一連のファイルを 1 つのエンティティまたは行セットとして扱いながら、それらに対して T-SQL クエリを実行するには、フォルダーのパス、または一連のファイルやフォルダーのパターン (ワイルドカードを使用) を指定します。To run a T-SQL query over a set of files within a folder or set of folders while treating them as a single entity or rowset, provide a path to a folder or a pattern (using wildcards) over a set of files or folders.

次の規則が適用されます。The following rules apply:

  • パターンは、ディレクトリ パスの一部またはファイル名に使用できます。Patterns can appear either in part of a directory path or in a filename.
  • 同じディレクトリ ステップまたはファイル名に複数のパターンを使用できます。Several patterns can appear in the same directory step or file name.
  • 複数のワイルドカードがある場合は、一致するすべてのパス内のファイルが、結果のファイル セットに含められます。If there are multiple wildcards, then files within all matching paths will be included in the resulting file set.
SELECT * FROM
OPENROWSET( BULK N'https://myaccount.dfs.core.windows.net/myroot/*/mysubfolder/*.parquet', FORMAT = 'PARQUET' ) as rows

使用例については、フォルダーと複数のファイルに対するクエリの実行に関する記事を参照してください。Refer to Query folders and multiple files for usage examples.

ファイル メタデータ関数File metadata functions

filename 関数Filename function

この関数は、行の生成元のファイル名を返します。This function returns the file name that the row originates from.

特定のファイルに対してクエリを実行するには、特定のファイルに対するクエリの実行に関する記事の「Filename」セクションをお読みください。To query specific files, read the Filename section in the Query specific files article.

戻り値のデータ型は nvarchar(1024) です。Return data type is nvarchar(1024). 最適なパフォーマンスを確保するために、filename 関数の結果は必ず適切なデータ型にキャストしてください。For optimal performance, always cast result of filename function to appropriate data type. 文字データ型を使用する場合は、適切な長さが使用されていることを確認します。If you use character data type, make sure appropriate length is used.

filepath 関数Filepath function

この関数は、完全パスまたはパスの一部を返します。This function returns a full path or a part of path:

  • パラメーターを指定せずに呼び出された場合、行の生成元である完全なファイル パスを返します。When called without parameter, returns the full file path that a row originates from.
  • パラメーターを指定して呼び出されると、パラメーターで指定された位置にあるワイルドカードと一致するパスの一部を返します。When called with parameter, it returns part of path that matches the wildcard on position specified in the parameter. たとえば、パラメーター値 1 は、最初のワイルドカードと一致するパスの一部を返します。For example, parameter value 1 would return part of path that matches the first wildcard.

追加情報については、特定のファイルに対するクエリの実行に関する記事の「Filepath」セクションをお読みください。For additional information, read the Filepath section of the Query specific files article.

戻り値のデータ型は nvarchar(1024) です。Return data type is nvarchar(1024). 最適なパフォーマンスを確保するために、filepath 関数の結果は必ず適切なデータ型にキャストしてください。For optimal performance, always cast result of filepath function to appropriate data type. 文字データ型を使用する場合は、適切な長さが使用されていることを確認します。If you use character data type, make sure appropriate length is used.

複合型と入れ子または繰り返しのデータ構造を操作するWork with complex types and nested or repeated data structures

(Parquet ファイルなどの) 入れ子または繰り返しのデータ型に格納されているデータのスムーズな操作を可能にするために、SQL オンデマンドに次の拡張機能が追加されています。To enable a smooth experience with data stored in nested or repeated data types, such as in Parquet files, SQL on-demand has added the extensions that follow.

入れ子にされたデータまたは繰り返しのデータを射影するProject nested or repeated data

データを射影するには、入れ子にされたデータ型の列を含む Parquet ファイルに対して SELECT ステートメントを実行します。To project data, run a SELECT statement over the Parquet file that contains columns of nested data types. 出力時、入れ子にされた値は JSON にシリアル化され、varchar(8000) SQL データ型として返されます。On output, nested values will be serialized into JSON and returned as a varchar(8000) SQL data type.

    SELECT * FROM
    OPENROWSET
    (   BULK 'unstructured_data_path' ,
        FORMAT = 'PARQUET' )
    [AS alias]

詳細については、Parquet の入れ子にされた型に対するクエリの実行に関する記事の「入れ子または繰り返しのデータを射影する」セクションを参照してください。For more detailed information, refer to the Project nested or repeated data section of the Query Parquet nested types article.

入れ子にされた列から要素にアクセスするAccess elements from nested columns

入れ子にされた列 (構造体など) から入れ子にされた要素にアクセスするには、"ドット表記" を使用して、フィールド名をパスに連結します。To access nested elements from a nested column, such as Struct, use "dot notation" to concatenate field names into the path. OPENROWSET 関数の WITH 句に column_name としてパスを指定します。Provide the path as column_name in the WITH clause of the OPENROWSET function.

構文フラグメントの例を次に示します。The syntax fragment example is as follows:

    OPENROWSET
    (   BULK 'unstructured_data_path' ,
        FORMAT = 'PARQUET' )
    WITH ({'column_name' 'column_type',})
    [AS alias]
    'column_name' ::= '[field_name.] field_name'

既定で、OPENROWSET では、ソース フィールドの名前とパスを WITH 句に指定された列名と一致させます。By default, the OPENROWSET function matches the source field name and path with the column names provided in the WITH clause. 同じソース Parquet ファイル内異なる入れ子レベルに含まれている要素には、WITH 句を使用してアクセスできます。Elements contained at different nesting levels within the same source Parquet file can be accessed via the WITH clause.

戻り値Return values

  • 関数では、入れ子にされた型グループに含まれていないすべての Parquet の型について、指定した要素から、および指定したパスで、int、decimal、varchar などのスカラー値が返されます。Function returns a scalar value, such as int, decimal, and varchar, from the specified element, and on the specified path, for all Parquet types that aren't in the Nested Type group.
  • パスが、入れ子にされた型の要素を指している場合、関数は、指定されたパスの先頭の要素から始まる JSON フラグメントを返します。If the path points to an element that is of a Nested Type, the function returns a JSON fragment starting from the top element on the specified path. JSON フラグメントの型は varchar(8000) です。The JSON fragment is of type varchar(8000).
  • 指定された column_name でプロパティが見つからない場合、関数はエラーを返します。If the property can't be found at the specified column_name, the function returns an error.
  • 指定された column_path でプロパティが見つからない場合、パス モードに応じて、関数は、strict モードのときはエラーを、lax モードのときには null を返します。If the property can't be found at the specified column_path, depending on Path mode, the function returns an error when in strict mode or null when in lax mode.

クエリのサンプルについては、Parquet の入れ子にされた型に対するクエリの実行に関する記事の「入れ子にされた列から要素にアクセスする」セクションを参照してください。For query samples, review the Access elements from nested columns section in the Query Parquet nested types article.

繰り返される列から要素にアクセスするAccess elements from repeated columns

配列やマップの要素など、繰り返される列から要素にアクセスするには、射影する必要があるすべてのスカラー要素に対して JSON_VALUE 関数を使用し、次を指定します。To access elements from a repeated column, such as an element of an Array or Map, use the JSON_VALUE function for every scalar element you need to project and provide:

  • 最初のパラメーターとして、入れ子にされた、または繰り返される列Nested or repeated column, as the first parameter
  • 2 番目のパラメーターとして、アクセスする要素またはプロパティを指定する JSON パスA JSON path that specifies the element or property to access, as a second parameter

繰り返される列から非スカラー要素にアクセスするには、射影する必要があるすべての非スカラー要素に対して JSON_QUERY 関数を使用し、次を指定します。To access non-scalar elements from a repeated column, use the JSON_QUERY function for every non-scalar element you need to project and provide:

  • 最初のパラメーターとして、入れ子にされた、または繰り返される列Nested or repeated column, as the first parameter
  • 2 番目のパラメーターとして、アクセスする要素またはプロパティを指定する JSON パスA JSON path that specifies the element or property to access, as a second parameter

次の構文フラグメントをご覧ください。See syntax fragment below:

    SELECT
       { JSON_VALUE (column_name, path_to_sub_element), }
       { JSON_QUERY (column_name [ , path_to_sub_element ]), )
    FROM
    OPENROWSET
    (   BULK 'unstructured_data_path' ,
        FORMAT = 'PARQUET' )
    [AS alias]

繰り返される列から要素にアクセスするためのクエリのサンプルについては、Parquet の入れ子にされた型に対するクエリの実行に関する記事をご覧ください。You can find query samples for accessing elements from repeated columns in the Query Parquet nested types article.

クエリのサンプルQuery samples

さまざまな型のデータに対するクエリの詳細については、サンプル クエリを参照してください。You can learn more about querying various types of data using the sample queries.

ツールTools

クエリを発行するために必要なツール:The tools you need to issue queries: - Azure Synapse Studio (プレビュー)Azure Synapse Studio (preview) - Azure Data StudioAzure Data Studio - SQL Server Management StudioSQL Server Management Studio

デモのセットアップDemo setup

最初の手順として、クエリを実行するデータベースを作成します。Your first step is to create a database where you'll execute the queries. 次に、そのデータベースでセットアップ スクリプトを実行して、オブジェクトを初期化します。Then you'll initialize the objects by executing setup script on that database.

このセットアップ スクリプトにより、データ ソース、データベース スコープの資格情報、これらのサンプルでデータの読み取りに使用される外部ファイル形式が作成されます。This setup script will create the data sources, database scoped credentials, and external file formats that are used to read data in these samples.

注意

このデータベースは、実際のデータではなくメタデータを表示するためにのみ使用されます。Databases are only used for viewing metadata, not for actual data. 使用するデータベース名を書き留めておきます。後で必要になります。Write down the database name that you use, you will need it later on.

CREATE DATABASE mydbname;

提供されるデモ データProvided demo data

デモ データには次のデータセットが含まれています。Demo data contains the following data sets:

  • NYC タクシー - イエロー タクシーの移動記録 - CSV および Parquet 形式のパブリック NYC データセットの一部NYC Taxi - Yellow Taxi Trip Records - part of public NYC data set in CSV and Parquet format
  • CSV 形式での母集団データ セットPopulation data set in CSV format
  • 入れ子になった列を含むサンプルの Parquet ファイルSample Parquet files with nested columns
  • JSON 形式の書籍Books in JSON format
フォルダー パスFolder path 説明Description
/csv//csv/ CSV 形式のデータの親フォルダーParent folder for data in CSV format
/csv/population//csv/population/
/csv/population-unix//csv/population-unix/
/csv/population-unix-hdr//csv/population-unix-hdr/
/csv/population-unix-hdr-escape/csv/population-unix-hdr-escape
/csv/population-unix-hdr-quoted/csv/population-unix-hdr-quoted
異なる CSV 形式の人口データ ファイルを含むフォルダー。Folders with Population data files in different CSV formats.
/csv/taxi//csv/taxi/ CSV 形式の NYC パブリック データ ファイルを含むフォルダーFolder with NYC public data files in CSV format
/parquet//parquet/ Parquet 形式のデータの親フォルダーParent folder for data in Parquet format
/parquet/taxi/parquet/taxi Parquet 形式の NYC パブリック データ ファイル。Hive または Hadoop パーティション構成を使用して年別および月別に分割されています。NYC public data files in Parquet format, partitioned by year, and month using Hive/Hadoop partitioning scheme.
/parquet/nested//parquet/nested/ 入れ子になった列を含むサンプルの Parquet ファイルSample Parquet files with nested columns
/json//json/ JSON 形式のデータの親フォルダーParent folder for data in JSON format
/json/books//json/books/ 書籍データを含む JSON ファイルJSON files with books data

次のステップNext steps

さまざまなファイルの種類に対してクエリを実行する方法、およびビューの作成と使用の詳細については、次の記事を参照してください。For more information on how to query different file types, and to create and use views, see the following articles: