自動クエリ プロバイダー

バージョン 2.384.99 以降、Windows の XLSX ワークブック ファサードで利用可能です。プロバイダーの自動選択が行われるのは、明示的なクエリ更新の実行時だけです

既存のクエリを更新する

Workbook.QueryProviders.BaseDirectory := 'C:\Data';
Workbook.QueryProviders.MaxInputBytes := 64 * 1024 * 1024;
Workbook.QueryProviders.MaxResultCells := 2000000;
Workbook.QueryProviders.TimeoutSeconds := 30;
Status := Sheet.RefreshQueryTable('ImportedData', 1000000);

TXLSXWorkbook.QueryProviders: TXLSQueryProviderDispatcher は、ワークブックが所有するディスパッチャーを lxQueryProviders から公開します。ディスパッチャーを自分で解放することはありません

TXLSXWorksheet.RefreshQueryTable(const AName: WideString; AMaxRows: Integer = 1000000; AOnProgress: TXLSQueryRefreshProgress = nil): Integer と、ゼロ始まりの AIndex を受け取るオーバーロードは、既存のクエリを選択してこのディスパッチャーを使用します

明示的な TXLSQueryTableProvider を受け取る既存のオーバーロードは、これまでどおりそのプロバイダーを直接使用します。プロバイダーが見つからない場合の拒否も従来どおりで、自動ディスパッチへのフォールバックは行いません

更新は成功時に 1、キャンセル時に 0、失敗時に -1 を返し、xlsOperationRefresh 配下の診断コードとして 1401 と 1400 が記録されます。既存のトランザクション方式の結果適用、スキーマ検証、リテラル文字列、書式設定の動作はそのまま有効です

これらの診断の名前は xlsDiagnosticQueryRefreshCancelled と xlsDiagnosticQueryRefreshFailed です。ステータス変換の前にワークブックの書き込みガードを取得するため、凍結された読み取りビューなど、書き込みガードによる拒否では例外が発生します

ワークブックのオープンや保存が、接続データの取得、クエリの評価、保持された RefreshOnLoad メタデータへの対応を行うことはありません。結果を保存する前に、必要な各クエリを明示的に更新してください

サポートされる組み込みプロバイダー

• xlckText は、ローカルの区切り形式または固定長テキストを、UTF-8、UTF-16LE、UTF-16BE、Windows-1252、Latin-1 の厳密なデコード、設定済みの開始行、6 種類の日付順やスキップ フィールドを含む対応フィールド型とともに読み込みます。区切り形式の入力では、引用符で囲まれた複数行レコードもサポートされます
• xlckAdo、xlckOleDb、xlckOdbc は、インストール済みの Windows ADO とデータベース ドライバーを読み取り専用の接続とレコードセットで使用します。CommandType = 2 で SQL テキストを、CommandType = 3 でテーブル コマンドを選択します
• xlckWeb は、Windows WinHTTP で匿名の HTTP または HTTPS GET を実行し、正のインデックスまたは名前で選択された空でない矩形の HTML テーブルを 1 つ取得します。対応するレスポンスの文字セットは UTF-8、UTF-16、Windows-1252、Latin-1 です

BaseDirectory が基準になるのは、相対パスのローカル テキストだけです。データベース接続文字列と Web URL は明示的な接続メタデータのまま扱われます

テキスト エンコーディングを未指定にした場合、対応するバイト オーダー マークでエンコーディングを識別できない限り、ASCII のみの入力しか受け付けません。非 ASCII の入力には、明示的な対応エンコーディングかバイト オーダー マークが必要です

区切り形式の Text 接続では、TextPrompt = False、TextDelimited = True とし、区切り文字は 1 つだけ設定します。連続する区切り文字は結合しません。新しく作成した接続はプロンプト表示とタブ区切りがデフォルトのため、別の区切り文字を選ぶときは TextTab をクリアしてください

固定長テキスト

TextPrompt = False と TextDelimited = False を設定し、TextFields をゼロ始まりの Position の厳密な昇順で、0 から追加します。各フィールドは次の位置または物理的なレコード終端で終わり、xltiftSkip を指定したフィールドは結果から除外されます

位置は入力バイトではなく、デコード後の UTF-16 コード単位で数えます。サロゲート ペアを分断する境界は拒否されます。CRLF、LF、CR は区切り文字や引用符 (qualifier) の設定とは無関係にレコードを終端します

フィールドのパディングは、明示的に型指定されたテキストを含めて変換前にトリミングされます。これは検証済みのネイティブ固定長インポートの動作と一致します。フィールド内の引用符、タブ、区切り文字はリテラル入力として扱われ、短いレコードでは宣言済みスキーマを変えずに末尾フィールドが空で補われます

TextFields がない場合、各レコードは 1 つの汎用フィールドになります。TextFirstRow で最初のスキーマ レコードを選択し、Query.Headers でそのレコードの値をスキップします。明示的な空レコードは行として残ります

既存の行数、入力バイト数、結果セル数、32767 コード単位のフィールド上限が適用されます。無効なメタデータ、変換失敗、過大な入力があると、トランザクション方式のワークシート更新の前にステージング データがクリアされ、キャンセル時は以前の結果セルが保持されます

Connection.TextPrompt := False;
Connection.TextDelimited := False;
Connection.TextFields.Add(xltiftGeneral, 0);
Connection.TextFields.Add(xltiftText, 8);
Status := Sheet.RefreshQueryTable('Imported');

Web 接続では、WebHtmlTables = True と WebHtmlFormat = 'none' を設定します。対応するリクエストは、埋め込み資格情報、フラグメント、認証、リダイレクトを拒否します

組み込みプロバイダーは、それぞれの接続種別で対応していないメタデータを拒否します。データベース更新は OLAP やサーバー コマンド、接続ファイルの間接参照、保存されたパスワード、資格情報プロンプトを拒否し、Text 更新はファイル プロンプトを拒否し、Web 更新は匿名のテーブル メタデータを要求します

型付きデータベース パラメーター

SQL テキスト コマンドは、Connection.Parameters の順序で ADO Command 経由でバインドされる位置指定 ? マーカーをサポートします。パラメーター値が SQL テキストを置き換えることはなく、名前は位置順序を変えずにバインドのラベルになります

プリフライトは、シングル クォート文字列、ダブル クォートやバッククォートの識別子、角かっこ識別子、行コメント、ネストしたブロックコメントの外側にあるマーカーを、クォートや角かっこの二重エスケープも含めて数えます。閉じていないクォートやコメント、マーカー数の不一致は、接続を開く前に拒否されます

ParameterType = 'value' には、xlcpvInteger、xlcpvDouble、xlcpvBoolean、xlcpvString のいずれかを明示的な ValueKind として、対応する値プロパティと組み合わせて指定します。0、False、空文字列も値として扱われ、xlcpvNone は実行時に値を推論しません

Connection.CommandType := 2;
Connection.CommandText := 'SELECT Amount FROM Sales WHERE Amount > ?';
with Connection.Parameters.Add do
begin
  Name := 'MinimumAmount';
  ParameterType := 'value';
  ValueKind := xlcpvInteger;
  IntegerValue := 0;
  SqlType := 4;
end;
Status := Sheet.RefreshQueryTable('SalesQuery');

ParameterType = 'cell'、ValueKind = xlcpvCell、CellReference は、Inputs!$A$1 や 'Sales Input'!B2 のような完全修飾のローカル ワークシート参照に使用します。引用符付きシート名のアポストロフィは二重化します。範囲、外部ワークブック、名前、修飾されていないセル参照は拒否されます

ワークシート更新は、再計算やパック セルのマテリアライズを行わずに、格納済みスカラー値と利用可能な数式キャッシュのスナップショットを取得します。数式キャッシュがないセルやエラー セルは拒否され、存在しないセルや空セルは、明示的に対応する SQL 型を指定した場合にのみ SQL null になります

セル スナップショットは Variant 型を保持するため、符号付き Int64、Currency、型付き日付、null の入力を、永続化用の 32 ビット整数や Double リテラル フィールドへ縮退させずに扱えます。直接格納された日付、null、Int64 リテラルはネイティブのパラメーター メタデータ モデルの対象外のため、これらの値には型付きセル バインディングを使用してください

SqlType は ODBC の SQL 型コードを使用し、ADO 型へ明示的にマッピングされます。ADO の DataTypeEnum 値ではありません

対応する明示的型は SQL null も受け付けます。配列、参照 Variant、エラー、非有限数、未対応の SQL 型、整数精度を失う変換は拒否されます。NUMERIC と DECIMAL は精度とスケールのメタデータを要求しますが、このバインディング API はそれを提供しません

ADO には型付きの値と宣言サイズが渡され、空テキストにも少なくとも 1 コード単位が割り当てられます。SQL ダイアレクト、対応パラメーター型、結果変換の責任はネイティブ ドライバー側に残るため、インストール済みプロバイダーが有効なバインディングを拒否したり、数値や日付の対応範囲が狭かったりする可能性はあります

Jet と ACE は、検証済みの DATE、TIME、TIMESTAMP 値に対して型付きの OLE DATE バインディングを使用し、ロケール依存のタイムスタンプ テキスト投影に左右されずに日付と時刻を保持します。DATE と TIME の検証規則はそのまま適用され、null 投影の可否はプロバイダー固有のままです

パラメーターには SQL テキスト コマンドが必要で、1 フェッチあたり 1024 個、名前あたり 255 コード単位、テキスト値あたり 32767 コード単位までに制限されます。コマンドテキスト、パラメーター参照、名前、ペイロードも入力バイトの予算を消費します

プロンプトや未知のパラメーター拡張属性は拒否されます。RefreshOnChange は保持メタデータのままで、バックグラウンド更新をトリガーしません。オープンや保存でセルが解決されたり、コマンドが実行されたりすることもありません

直接の Fetch はリテラルをサポートします。FetchWithCellResolver(Connection, Query, MaxRows, out Data, var Abort, AResolver) はセル値のための TXLSQueryParameterCellResolver コールバックを受け取り、その Boolean 結果は格納値が利用可能かどうかを示します

コールバックの有効範囲はその呼び出しに限られ、保持されません。自動ワークシート更新はローカル リゾルバーを供給し、登録済みカスタム プロバイダーは引き続き優先され、パラメーターのセマンティクスを自身で決めます

Web 更新は、span セル、ネストした選択テーブル、スクリプト駆動コンテンツを含まない plain な text/html テーブルをサポートします。未対応のレイアウトやエンティティは部分的なデータを作るのではなく拒否されます

カスタム プロバイダーを登録する

Workbook.QueryProviders.RegisterProvider(xlckWeb, CustomProvider);
try
  Status := Sheet.RefreshQueryTable('RemoteData');
finally
  Workbook.QueryProviders.RegisterProvider(xlckWeb, nil);
end;

TXLSQueryProviderDispatcher.Create は直接使用のための独立所有のディスパッチャーを構築します。ワークブックは自身のインスタンスを作成して所有します

RegisterProvider(AKind: TXLSConnectionKind; AProvider: TXLSQueryTableProvider) は宣言された接続種別に借用ハンドラーを登録し、nil で登録解除します。ハンドラーは登録期間中生存している必要があります

登録されたハンドラーは組み込みプロバイダーより優先され、アプリ固有の認証や接続種別をサポートできます。フェッチ中の登録変更、設定変更、再帰ディスパッチは拒否され、無効な enum 値は配列アクセスの前に拒否されます

Fetch(Connection, Query, MaxRows, out Data, var Abort) はワークシート更新の際に切り離されたメタデータを受け取り、矩形の TXLSQueryResultData を返します。キャンセルや例外が起きると、伝搬の前にステージング結果がクリアされます

リソース上限

MaxInputBytes のデフォルトは 67108864 バイトで、Text や Web の入力、対応データベースの結果ペイロードを制限します。MaxResultCells のデフォルトは 2000000 セルで、矩形の結果を制限します

TimeoutSeconds のデフォルトは 30 で、対応するネイティブ データベースや HTTP の各フェーズを設定します。操作全体やカスタム プロバイダーに対する保証付きの期限ではありません

3 つの設定値と MaxRows はすべて正の値でなければならず、タイムアウトはネイティブのミリ秒整数に収まる必要があります。ディスパッチャーは超過した行、列、セルを切り詰めずに拒否します。バイト数と入力の上限は組み込みプロバイダーが強制し、カスタム フェッチでは登録ハンドラーの責任のままです

ワークシート更新はすべての結果値を検証し、キャンセルやアプリケーション エラーの後にはセルとクエリ・テーブルのメタデータを復元します。外部操作の上限を守る責任はカスタム プロバイダー側に残ります

ネイティブ XLSX 結果バインディング

テーブルに裏付けられたデータベース クエリは、テーブルとクエリ テーブルのリレーションシップ、整合するフィールド ID、列識別子、隠されたローカルの宛先名を使用します。単独でサポートされる Text と Web の宛先は結果範囲を保持します

TXLSXTable.ColumnUniqueNames[Index]: WideString はゼロ始まりのネイティブ列識別子を公開し、ColumnQueryTableFieldIds とともに代入、コピー、再オープンを通じて保持されます

外部テーブルとして直接バインドされた旧式の Text 接続は、ネイティブ エクスポートとしてサポートされる形状ではなく、保存時に出力前に拒否されます。明示的に更新したテキスト値で通常のテーブルを作るか、インストール済みの ADO/ODBC テキスト ドライバーでネイティブなテーブル裏付けのデータベース クエリを提供できます

無関係または未対応のインポート済みリレーションシップと拡張 XML は引き続き保持されます。この機能が不透明な外部グラフを、対応する更新可能なクエリへ変換することはありません

宛先の検証、進行状況コールバック、周辺のメタデータ モデルについては、接続とトランザクション クエリの API を参照してください