MAD Designer iconMAD

MAD SQL Entry — SQLクエリをクエリデザイナに貼り付ける

このページはSQL入力機能を記録します。サポートされるSELECTサブセット、パーサとリゾルバ、およびステートメントをポータブルなクエリグラフに戻す適用パスです。Phase A〜Dは実装済みで、Phase Eは延期されています。

スコープ: MAD/Source/sql/の新しいパーサ/リゾルバ/コンパイラ、MADocument上の適用パス、MADDesignerのSQLポップオーバー、永続化されるソーステキスト(§8、ストアの最初のバージョニングステップを追加)、およびそれらすべてを固定するテスト。 日付: 2026-10-22、cf0fe3acdで読了。2026-10-22に永続化の決定(§8)で改訂。 ステータス: 実装済み——Phase A〜Dは2026-10-22に着地し、c48a39fb7としてmasterにマージされました(内部タスクキュー§16)。Phase E(§9)は延期されたままです。§8.1〜§8.2は実装どおりの修正を伝えます。


1. 目標

今日、クエリを構築する唯一の方法はビジュアルデザイナです。テーブルを選び、フィールドごとにリンクし、フィルタを追加し、グループ化を追加します——すべてタブ付きUIを通じて。ユーザーは2つ目の入口を望んでいます。

「……ユーザーがボタンを押すと画面が反転し、マルチラインのテキストビューが表示されてSQLを貼り付けられる……そのSQLが保存されると、バックエンドでレポートのクエリを手動で作成する……ユーザーがすべての詳細を選択するのと同じことをすべて行う……ソフトウェアはどのフィールドが使われ、どの結合が使われ、どのテーブルが使われたかを依然として認識し、ドキュメントを適切な方法で完全にセットアップし、その後ユーザーが望めば標準クエリで入力されたフィールドでクエリデザイナを使うことさえできる。」

つまり、貼り付けられたSQLはドキュメントのクエリモデル(Rptqオブジェクトグラフ)に、ビジュアルデザイナが呼ぶのとまったく同じファクトリを通じてコンパイルされます。適用後、ビジュアルクエリデザイナ、ビジュアライゼーションキャンバス、レポートデザイナは、クエリが手で構築されたかのように見えます——そしてユーザーはそこで編集を続けられます。検証フェーズが必要です。

2. 今日存在するもの(直接読んだ)

2.1 正規クエリモデル — Rptqグラフ

ドキュメントのクエリはポータブルストアにプレーンなRptq*オブジェクトとして存在し(MAD/Source/rptq/)、MADModel*レイヤーはそれらの上への読み取り専用ビューです(MADModel_Layer.md)。インポータはRptq行だけを書き、それ以外は書きません。

モデルが保持しないもの——インポータが尊重しなければならない境界:

2.2 SQL生成 — ラウンドトリップ契約

MADQueryFullはモデルから実行SQLを構築します(SQLOnlyActiveFields:managedObjectContext:error:、MADQueryFull.m:143-273)。

したがってインポータの契約は次のとおりです。貼り付けられたステートメントは、あるモデルに対してMADQueryFullの出力であり得る場合に正確に受け入れ可能です。 これがラウンドトリップを正直にします。SQLポップオーバーのView側はインポートされたモデルから再生成されたSQLを表示し、それはユーザーが貼り付けたもののように読めます。

2.3 リフレッシュパイプライン — 検証が再利用するパターン

MADOperationRefresh.m:60-172: オペレーション依存から供給される認証情報で接続し、メインキュー上でSQLを構築し(ストアコンテキストはメインキュー所有——BUGS.md)、次に[database executeSQL:fieldKeys:onConnection:intoResultTable:withError:](MADDatabaseProtocol.h:33)とdataTableMakeCache。検証プローブはキャッシュ構築を除いた同じオペレーション形状です。

2.4 UIがすでに呼ぶバックエンド — コンパイラが再利用するシーム

Rptq行を書いて保存するだけで十分です。MADModel*レイヤーはストア通知を通じて変更をUIにミラーします(MADModel_Layer.md §3.3)。今日のUIコードからそのまま呼ぶファクトリ:

2.5 UIシーム

クエリビルダのスプリットビューコントローラはすでにbarButtonItemSQLツールバー項目を持ち、読み取り専用のMADViewControllerSQLポップオーバーを提示します(MADQueryBuilderSplitViewController.m:31, 106-111、MADQuery.storyboard、MADViewControllerSQL.m:27-56は[doc.mainQuery SQLOnlyActiveFields:…]を表示)。機能はこの同じ画面のモードであるため、ボタン、ポップオーバー、ナビゲーションはすべて存在します。

3. ユーザーが見る機能

  1. クエリタブで既存のSQLボタンをタップします。ポップオーバーはView / Editモードを持ちます。
  2. ViewはクエリのSQLの両方の表現をセグメントコントロールとして表示します。
    • Generated — MADQueryFullが今モデルから構築するSQL(今日のポップオーバー内容をデフォルトタブとして保持)。
    • As entered — ユーザーが最後に適用したステートメントそのまま(RptqQuery.sqlSourceText、§8)。クエリが貼り付けSQLから構築されたことがない場合は非表示か空です。 両方のタブは読み取り専用です——「貼り付けたものと、それが何になったかを見る」画面。
  3. Edit — 等幅のマルチラインテキストビュー。sqlSourceTextがある場合はそこからシードされ(ユーザーは自分のテキストを、書式とコメントを保ったまま再編集します)、そうでなければ生成SQLからシードされます。Revert to generatedボタンが生成形式から再シードします。
  4. Validate — 構造チェックと、ドキュメントのデータベースに到達できる場合のゼロ行サーバープローブ(§7)。エラーは行と列付きで返ります。
  5. Apply — ステートメントがドキュメントにコンパイルされ(アトミック——§6.5)、貼り付けたテキストそのものがsqlSourceTextとして永続化されます(§8)。ポップオーバーが閉じ、クエリテーブルリスト、ビジュアライゼーションキャンバス、レポートデザイナがすべてインポートされた構造を表示します。デザイナのフィールドピッカーは通常どおり動作します。
  6. 失敗または競合した適用は何も永続化しません——テキストも、行も。以前のクエリと以前の入力テキストはまったくそのまま残ります。
  7. ユーザーはいつでも戻れます。ビジュアルデザイナはインポートされたクエリで動作し続け、Viewは両方の形式を表示し、Editはユーザー自身の言葉を再び開きます。

4. アーキテクチャ

pasted SQL
  → MADSQLTokenizer        dialect-aware lexer; quotes per driver; tracks line:column
  → MADSQLParser           recursive descent; produces a MADSQLStatement parse tree
  → MADSQLStatementResolver  binds names to RptqDatabaseSchemaTable / RptqDatabaseSchemaField
  → [MADOperationValidateSQL]  server probe, when connected (§7); never writes
  → MADSQLQueryCompiler    the write plan: deletes + creates Rptq rows via the §2.4 factories
  → store save → model notifications → query UI / visualization / designer update

配置。 プローブオペレーションとエディタUIを除くすべてがMADフレームワークにあり、純粋なFoundationでUIKitなしです。そのためMADテストスイートとLinuxイメージで実行されます。新しいファイルはLinux/cmake/MADSources.cmakeに載り、./Linux/build.shはグリーンを保ちます。プローブオペレーション(ドライバ、認証情報、UIKitアラートが必要)とポップオーバーUIはMADDesigner/Sourceにあります。

新しいファイル。 MAD/Source/sql/MADSQLTokenizer.{h,m}、MADSQLParser.{h,m}、MADSQLStatement.{h,m}(ツリーとその値型: MADSQLColumnReference、MADSQLPredicateTerm、……)、MADSQLStatementResolver.{h,m}、MADSQLQueryCompiler.{h,m}、MADSQLCompileError.{h,m}。アプリ: MADOperationValidateSQL.{h,m}(MADOperationRefreshをミラー)、および同じストーリーボードシーム内のMADViewControllerSQLまたは兄弟エディタコントローラのエディタ変更。

小さなAPI追加。 レキサは接続が存在する前に各方言の識別子引用(MySQLのバッククォート、T-SQLのブラケット、二重引用符)を必要とします。MADDatabaseに+ (NSString *)identifierQuoteCharactersを追加し(デフォルト: 二重引用符)、MADMySQL/MADTdsClientでドライバごとに上書きします(MADPostgresはデフォルトの二重引用符を使います)——または好みなら、MADDatabaseDriverRegistryを通じて解決されるドライバプロトコルのクラスメソッド。いずれにせよ3メソッドの追加です。

5. サポートされるサブセット

インポータはモデルが保持できる言語を正確に受け入れます——1つのSELECT、どこにもサブクエリなし、各句は§2.1の制限内です。

リテラルは生成時に方言ごとに処理されます(newSafeLiteral:、MADDatabaseSQLProtocol.h)。インポータは述語UIとまったく同じように、値文字列とフィールドのデータ型だけを記録します(MADQueryPredicate.m:74-88)。

拒否は決して静かではありません。すべてが構文、句、理由(どのモデル制限に当たるか)、および行:列を名指しします。

6. 解決とコンパイル

6.1 リゾルバ

6.2 書き込みプラン

リゾルバの出力は値オブジェクトのプランです。順序付きテーブルリスト、結合リスト(結合ごとのMADLinkType)、述語リスト(MADPredicateOperator + 左/右項)、ソート順付きグループリスト。プランは何かが書かれる前に全体として検証されます。

6.3 競合チェック — 適用はアトミック

適用はクエリを置き換えます(貼り付けられたSQLがクエリです——それが機能です)。書く前に、新しいプランが含まないすべてのテーブルについて、デザイナ要素からの参照をチェックします——MADQueryActiveQueryFieldsが知る3つの形状(MADQueryActiveQueryFields.m:37-68: ラベルデータ、集計、バーコード参照)と、削除されるグループセクション。削除されたテーブルのフィールドが参照されている場合、要素を名指しするエラーで中止します(「このフィールドはデザイナの……で使われています」)。何も削除されず、何も書かれず、古いクエリは依然として実行されます。これはインポートがアトミックかつ静かであり得ない唯一のケースであり、そのため大声で失敗します。

6.4 書き込み

逆依存順で§2.4のヘルパーを使って: リンクと述語を削除し、グループを削除し(既存のグループ削除パス経由で、セクションとレイアウトマネージャを切り離します)、プランにないテーブルを削除し(既存のdeleteDatafieldsRelatedToTable:ファミリ経由)、次にUIが呼ぶのと同じファクトリを通じてテーブル → リンク → 述語 → グループを作成します。1回の保存。呼び出し元はその後ドキュメントをダーティにし、add-tableフローがするように自動保存します(MADQueryViewController.m:796-799)。

6.5 書き込みの後

UIを突つきません。ストア通知パスがモデルレイヤーと両方のクエリ画面を更新します(MADModel_Layer.md §3.3)。コンパイラはポップオーバーのためにサマリ(テーブル/リンク/述語/グループの数)を返します。

7. 検証 — 2つのレベル

構造的(常に、オフライン)。 パース+解決、§5〜§6。エラーはMADSQLCompileErrorドメインのNSErrorで、コード、行、列、メッセージを持ちます。ドキュメントのデータベースに到達できない場合、これが機能のすべてです。

サーバープローブ(接続できる場合)。 ステートメントをラップします。

SELECT * FROM (<user sql>) AS _mad_probe WHERE 1=0

派生テーブルのエイリアスはMySQLで必須でT-SQLで有効です。WHERE 1=0は折り畳まれるため、プローブはクエリをコンパイルし、行を読まずに列メタデータを返します。MADOperationRefreshの形状(MADOperationRefresh.m:104-162)で実行します。オペレーション依存からの認証情報で接続し、ストア読み取りをメインキューにマーシャルし、結果はドライバのexecuteSQL:…intoResultTable:…経由で得て、MADDataColumnが名前と型を与えます。プローブは静止解析ができないものを捕捉します。サーバーサイドの名前解決(大文字小文字の区別、ビュー、予約語)、方言差、サーバー自身の構文エラーで、サーバーのメッセージとともに表面化されます。列名/型は解決されたスキーマフィールドと比較され、不一致は失敗ではなく警告として報告されます。

オフライン、または認証情報が利用できない場合、プローブはスキップされ、UIは「構造によってのみ検証済み」と表示します。

8. 永続化されるソーステキスト — RptqQuery.sqlSourceText

コンパイルされたモデルは実行のための真実の源のままですが、ユーザーが貼り付けたテキストはドキュメントの一部です。RptqQueryの新しいNULL可能テキスト属性sqlSourceTextが、最後に正常に適用されたステートメントをそのまま保持します。ユーザーの言葉を削除することは決して選択肢ではありませんでした——ドキュメントは入力とそのコンパイルの両方を保ちます。ユーザーは履歴配列ではなく単一プロパティを選びました(2026-10-22)。リビジョン履歴は後で順序付きto-manyとして追加し、現在のテキストからデータ損失なしでバックフィルできます。

永続化ルール:

8.1 ストア変更

属性はスキーマのクロスチェックの両側に着地します。コンパイルされたモデルと手で維持されるMADStoreSchema記述子、およびRptqQueryのautogenプロパティ(MAD/Source/rptq/autogen/)。MAD_FORMAT.mdはそのフィールドリストに列を獲得します。

修正(Phase A、2026-10-22)。 モデル変更は新しいMAD 4.xcdatamodelバージョンであり、その場でのMAD 3編集ではありません。出荷済みモデルバージョンのハッシュはすべての野生のドキュメントのストアメタデータを固定し、それを編集するとそれらを孤児にします。MAD 4はまた、RptqDocumentElementBarcode.barcodeBorderTypeの死んだelementID="type"を落とします(MAD 3以前のバージョンにバーコードエンティティはありません。BUGS.md)。

8.2 ストアバージョニング — 新しく、小さく、今や必須

ポータブルストアには今日バージョニングがありません(MADStore.mはuser_versionプラグマを持ちません)。このフェーズは機構を追加し、意図的に最小限にします。

修正(Phase A、2026-10-22)。 MADStoreConverterは各レガシーストアをそのメタデータに一致するmomdバージョンで開くようになり、自動マイグレーションは決して使いません。Core Dataはこのモデルファミリのマッピングを推測できず(バーコードのelementID衝突、BUGS.md)、momd-currentモデルはもはや野生のストアが書かれたバージョンではないからです。

8.3 検討して却下: gutsメタデータplist

gutsディレクトリでストアの隣に乗るメタデータplistは、スキーマ変更なしでテキストを保持できました。却下: クエリデータはストアのクエリ部分に属し(MADStorePartQuery——ストアの契約は「3つの部分とそれ以外何もない」、MADStoreSchema.h:12-13)、ヘッドレスエンジンはplistではなくストアを読みます。

8.4 これがアンブロックする未来

保存された入力テキストは、製品の地平線にあるエージェント駆動のクエリ設計(MAD_FUTURE.md)の自然な入力表面です。エージェント——または人——がステートメントを書き、下のコンパイラがそれをドキュメントに変え、sqlSourceTextが記録のプロンプトを保ちます。厳格なコンパイル済みモデルアーキテクチャがそのステップワイズを可能にします。書き手がエージェントになってもコンパイラについて何も変わりません。

9. フェーズ

Phase A — 永続化されるソーステキスト: ストアバージョニング(MADのみ。Linuxグリーン)。

  1. RptqQueryのsqlSourceText: コンパイル済みモデル+MADStoreSchema記述子+autogenプロパティを1つの変更で(さもなければクロスチェックテストが失敗します)。
  2. §8.2のバージョニング機構——バージョン定数、マイグレーションリスト、オープン時のuser_version読み取り/適用/書き込み、現在のバージョンでの新規ストア。
  3. テスト: MADStoreSchemaTestsが両側でグリーンを保つ。新しいマイグレーションテスト(§10.2)。MAD_FORMAT.md更新。

受け入れ: このフェーズ以前に作成されたドキュメントがきれいに開き、列を得て、データを保ち、Linuxを通じてラウンドトリップする。新しいドキュメントは現在のバージョンで生まれる。このフェーズは自己完結しており、パーサより先に、独立して着地します。

Phase B — ゴールデンテスト、次にパーサ(MADのみ。Linuxグリーン)。

  1. MADQueryFullの方言ごとの正確な出力を固定するゴールデンSQLテスト(§10.1)——先に書き、パーサが実際のジェネレータに対して構築されるようにする。
  2. MADSQLTokenizer/MADSQLParser/MADSQLStatement + 識別子引用API(§4)。
  3. MADSQLParserTests — §5の受け入れ/拒否マトリックス、エラーコード、行:列。

受け入れ: MADQueryFullが出力できるすべてのサポート構文がパースされる。拒否されたすべての構文がコード付きの位置エラーで失敗する。MADスイートと./Linux/build.shがグリーン。

Phase C — リゾルバ+コンパイラ(MADのみ。Linuxグリーン)。

  1. MADSQLStatementResolver、アトミック適用(§6)と成功時のsqlSourceText書き込み(§8)を持つMADSQLQueryCompiler。
  2. 削除ヘルパーの棚卸し。欠けているリンク/述語削除ヘルパーを追加。
  3. MADSQLQueryCompilerTests + 不動点ラウンドトリップテスト(§10.4)。

受け入れ: ステートメントを適用すると、ビジュアルデザイナが作ったであろうRptq行を正確に生成し、テキストをそのまま保存する。既存クエリの上に適用しても孤児が残らない。競合ケースはストア——および以前のテキスト——に触れずに中止する。不動点テストが通る。

Phase D — アプリ(MADDesigner)。

  1. §3のView/Editポップオーバー、MADOperationValidateSQLプローブ、サマリビュー。
  2. サンプルドキュメント(sqlite3ドライバ——サーバー不要)を使うUIテスト(§10.6)。

受け入れ: 貼り付け → 検証 → 適用で、クエリデザイナとビジュアライゼーションにテーブル/結合/述語が、レポートデザイナにグループセクションが表示され、リフレッシュがクエリを実行する。Viewは生成SQLと入力テキストの両方を表示する。ドキュメントを閉じて再度開いても入力テキストが保たれる。

Phase E — 延期、独自の決定。

10. テスト

10.1 既存機能の固定(先に書く)

10.2 ストア永続化とマイグレーションのテスト

10.3 パーサテスト — MADSQLParserTests(MAD)

10.4 コンパイラテスト — MADSQLQueryCompilerTests(MAD)

スキーマフィクスチャ付きインメモリストア(MADModelQueryTableTestsが使うパターン):

10.5 検証テスト

10.6 UIテスト — MADDesignerUITests

サンプル.mad(sqlite3ドライバ)で: SQLポップオーバーを開き、Editに切り替え、フィルタとグループ付きの2テーブル結合を貼り付け、Applyし、クエリテーブルリストが両方のテーブルを表示し、ビジュアライゼーションキャンバスが2つのボックスとコネクタを表示し、デザイナがグループセクションを表示し、Viewモードが再生成SQLを表示することをアサート。次にドキュメントを閉じて再度開く。As enteredタブは依然として貼り付けたテキストを正確に表示し、Generatedタブは依然としてコンパイルされたクエリのSQLを表示する——ドキュメントは両方を保った。

10.7 テストのための設計制約(実装者に拘束力)

11. 決定 — ユーザーと解決済み(2026-10-22)

  1. 厳格なサブセット。 確認済み: モデルが保持できないものは理由とともに拒否されます(§5)。不透明SQLのフォールバックはありません。
  2. 適用はクエリを置き換える(アトミック、§6.3)。確認済み。
  3. GROUP BYのインポートはレポートのグループセクションを自動的に作成する——既存のMADocumentヘルパーがこれを行い、まったくそのまま残ります。確認済み。
  4. SELECTリストはPhase Eまで検証されるが保存されない——要素合成が存在するまで、インポートされたクエリはユーザーが要素を追加するまで結合/グループ列をリフレッシュで返し、新しいドキュメントとまったく同じです。段階的として確認済み。
  5. 貼り付けられたテキストは永続化される。 確認済み——RptqQueryのsqlSourceText、最後に正常に適用されたステートメントを保持する単一プロパティ(§8)、Generatedの隣にAs enteredとして表示。生成形式はリフレッシュが実行するもののままで、テキストが保存されることは実行を変えません。履歴配列は検討され、脇に置かれました(§8、Phase E)。

このページは英語原文の日本語翻訳です。内容に相違がある場合は、英語原文が優先されます。