mORMot2 獲取數據集

其實在前面想學習mORMot1部分已經收集了很多關於CRUD的示例了，但感覺總是不通透，不能很好使用，一則mORMot函數命令規則比較不同尋常，另外確實示例太少，其實代碼註釋倒是講了很多。

procedure FillPrepare(Table: TOrmTable; aCheckTableName: TOrmCheckTableName = ctnNoCheck); overload;

FillPrepare 程式是為了從 TOrmTable 結果中準備獲取值。

• 在準備之後，你可以調用 FillRow(1..Table.RowCount) 來獲取任何一行的值。
• 或者，你也可以使用以下迴圈來遍歷所有行：

while Rec.FillOne do
  dosomethingwith(Rec);

• 在這個過程中，指定的 TOrmTable 被存儲在一個受保護的內部欄位 fTable 中。
• 如果你想獲取表中的欄位名，可以設置 aCheckTableName 參數。在匹配到當前記錄之前，任何待處理的 'TableName.' 首碼都將被去除。

註意：這裡的 dosomethingwith(Rec); 是一個占位符，代表你可以對每一行記錄 Rec 執行某些操作。實際使用時，你需要將其替換為具體的業務邏輯代碼。同時，Rec 應該是一個已經定義好的記錄類型變數，用於存儲從 TOrmTable 中獲取的數據。

另外，TOrmCheckTableName 是一個枚舉類型，ctnNoCheck 是它的一個值，表示不進行表名檢查。如果你需要檢查表名，可以傳遞其他相應的枚舉值給 aCheckTableName 參數。

function FillPrepare(const aClient: IRestOrm; const aSqlWhere: RawUtf8 = ''; const FieldsCsv: RawUtf8 = ''; aCheckTableName: TOrmCheckTableName = ctnNoCheck): boolean; overload;

FillPrepare 函數用於從 SQL WHERE 語句中獲取值。

• 如果 SQL 請求成功，則返回 true，如果在 SQL 請求期間發生錯誤，則返回 false。
• 準備完成後，你可以通過調用 FillRow(1..Table.RowCount) 來獲取任何一行的值。
• 或者，你也可以使用以下迴圈來遍歷所有行：

while Rec.FillOne do
  dosomethingwith(Rec);

• 函數會創建一個臨時的 TOrmTable，並將其存儲在一個受保護的內部欄位 fTable 中。
• 如果 aSqlWhere 留空（''），則會儘快檢索所有行（例如，通過繞過外部資料庫的 SQLite3 虛擬表模塊）。
• WHERE 子句應使用內聯參數（如 'Name=:('Arnaud'):'）以提高伺服器速度。請註意，你可以像這樣使用 FormatUtf8()：

aRec.FillPrepare(Client, FormatUtf8('Salary>? AND Salary<?', [], [1000, 2000]));

或者直接使用帶有 BoundsSqlWhere 參數數組的 FillPrepare() 方法的重載版本。

• FieldsCsv 可用於指定必須檢索哪些欄位。
• 預設的 FieldsCsv='' 將檢索所有簡單的表欄位，但如果你只需要訪問一個或多個欄位，並希望節省遠程帶寬，可以通過指定所需欄位來實現。
• 如果 FieldsCsv='*'，它將檢索所有欄位，包括 BLOBs。
• 請註意，如果你想稍後更新檢索到的記錄內容，則不應使用此可選的 FieldsCsv 參數，因為任何缺失的欄位都將保留先前的值。但是，在 FillPrepare 之後可以安全地使用 BatchUpdate()（將僅設置 ID、TModTime 和映射的欄位）。

function FillPrepare(const aClient: IRestOrm; const FormatSqlWhere: RawUtf8; const BoundsSqlWhere: array of const; const FieldsCsv: RawUtf8 = ''): boolean; overload;

使用帶有 '%' 參數的指定 WHERE 子句準備獲取值。

• 如果 SQL 請求成功，則返回 true，如果在 SQL 請求期間發生錯誤，則返回 false。
• 準備完成後，你可以通過調用 FillRow(1..Table.RowCount) 來獲取任何一行的值。
• 或者，你也可以使用以下迴圈來遍歷所有行：

while Rec.FillOne do
  dosomethingwith(Rec);

• 函數會創建一個臨時的 TOrmTable，並將其存儲在一個受保護的內部欄位 fTable 中。
• 為了提高伺服器速度，WHERE 子句應使用在 FormatSqlWhere 語句中標識為 '?' 的綁定參數，這些參數應按照 BoundsSqlWhere 開放數組中提供的值的順序進行排列。對於 TDateTime 類型，使用 DateToSql/DateTimeToSql，或者直接將任何整數/雙精度/貨幣/RawUtf8 值綁定為請求的參數。
• 請註意，此方法原型在框架的 1.17 版中已更改：以前 ParamsSqlWhere 是 array of const 類型，併在 FormatSqlWhere 語句中使用 '%'，而現在它期望綁定參數為 '?'。
• FieldsCsv 可用於指定必須檢索哪些欄位。
• 預設的 FieldsCsv='' 將檢索所有簡單的表欄位，但如果你只需要訪問一個或多個欄位，並希望節省遠程帶寬，可以通過指定所需欄位來實現。
• 如果 FieldsCsv='*'，它將檢索所有欄位，包括 BLOBs。
• 請註意，如果你想稍後更新檢索到的記錄內容，則不應使用此可選的 FieldsCsv 參數，因為任何缺失的欄位都將保留先前的值。但是，在 FillPrepare 之後可以安全地使用 BatchUpdate()（將僅設置 ID、TModTime 和映射的欄位）。

function FillPrepare(const aClient: IRestOrm; const FormatSqlWhere: RawUtf8; const ParamsSqlWhere, BoundsSqlWhere: array of const; const FieldsCsv: RawUtf8 = ''): boolean; overload;

使用帶有 '%' 和 '?' 參數的指定 WHERE 子句準備獲取值。

• 如果 SQL 請求成功，則返回 true，如果在 SQL 請求期間發生錯誤，則返回 false。
• 準備完成後，你可以通過調用 FillRow(1..Table.RowCount) 來獲取任何一行的值。
• 或者，你也可以使用以下迴圈來遍歷所有行：

while Rec.FillOne do
  dosomethingwith(Rec);

• 函數會創建一個臨時的 TOrmTable，並將其存儲在一個受保護的內部欄位 fTable 中。
• FormatSqlWhere 子句會將所有 '%' 字元替換為提供的 ParamsSqlWhere[] 數組中的值，並將所有 '?' 字元綁定為 BoundsSqlWhere[] 數組中的綁定參數值。
• FieldsCsv 可用於指定必須檢索哪些欄位。
• 預設的 FieldsCsv='' 將檢索所有簡單的表欄位，但如果你只需要訪問一個或多個欄位，並希望節省遠程帶寬，可以通過指定所需欄位來實現。
• 如果 FieldsCsv='*'，它將檢索所有欄位，包括 BLOBs。
• 請註意，如果你想稍後更新檢索到的記錄內容，則不應使用此可選的 FieldsCsv 參數，因為任何缺失的欄位都將保留先前的值。但是，在 FillPrepare 之後可以安全地使用 BatchUpdate()（將僅設置 ID、TModTime 和映射的欄位）。

這個函數結合了兩種參數替換方式：'%' 字元的直接替換和 '?' 的綁定參數方式，為用戶提供了更大的靈活性。但同時，也要求用戶更仔細地管理參數以避免潛在的 SQL 註入風險。

function FillPrepare(const aClient: IRestOrm; const aIDs: array of TID; const FieldsCsv: RawUtf8 = ''): boolean; overload;

準備從一個ID列表中獲取值。

• 如果SQL請求成功，則返回true，如果SQL請求期間出現錯誤，則返回false。
• 準備完成後，你可以通過調用 FillRow(1..Table.RowCount)來獲取任何一行的值。
• 或者，你也可以使用以下迴圈來遍歷所有行：

while Rec.FillOne do
  dosomethingwith(Rec);

• 函數會創建一個臨時的 TOrmTable，並將其存儲在一個受保護的內部欄位 fTable中。
• FieldsCsv可用於指定必須檢索哪些欄位。
• 預設的 FieldsCsv=''將檢索所有簡單的表欄位，但如果你只需要訪問一個或多個欄位，並希望節省帶寬，可以通過指定所需欄位來實現。
• 如果 FieldsCsv='*'，它將檢索所有欄位，包括BLOBs。
• 請註意，如果你想稍後更新檢索到的記錄內容，則不應使用此可選的 FieldsCsv參數，因為任何缺失的欄位都將保留先前的值。但在 FillPrepare之後可以安全地使用 BatchUpdate()（只會設置ID、TModTime和映射的欄位）。

這個重載版本的 FillPrepare函數接收一個ID數組作為參數，使得用戶能夠一次性檢索多個特定ID對應的記錄，提高了數據檢索的效率。同時，與上一個版本類似，它也支持通過 FieldsCsv參數來定製需要檢索的欄位，以滿足不同的數據需求。

function FillPrepareMany(const aClient: IRestOrm; const aFormatSQLJoin: RawUtf8; const aParamsSQLJoin, aBoundsSQLJoin: array of const): boolean;

準備遍歷包含 TOrmMany欄位的JOIN語句。

• 所有 TOrmMany.Dest發佈的欄位現在將包含一個真正的 TOrm實例，準備好用JOIN語句的結果填充（這些實例將在 FillClose時釋放）——Source也將指向自身實例。
• aFormatSQLJoin子句將為自動化的JOIN語句定義一個WHERE子句，包括 TOrmMany發佈的屬性（及其嵌套屬性）。
• 如果SQL請求成功，則返回true，如果SQL請求期間出現錯誤，則返回false。
• 一個典型的應用場景可能如下：

if aProd.FillPrepareMany(Database,
    'Owner=? and Categories.Dest.Name=? and (Sizes.Dest.Name=? or Sizes.Dest.Name=?)',
    [], ['mark', 'for boy', 'small', 'medium']) then
  while aProd.FillOne do
    // 在這裡，例如，aProd.Categories.Dest被實例化（並且Categories.Source=aProd）
    writeln(aProd.Name, ' ', aProd.Owner, ' ', aProd.Categories.Dest.Name, ' ', aProd.Sizes.Dest.Name);
// 你也可以使用aProd.FillTable來填充一個網格，例如
// （不要忘記設置aProd.FillTable.OwnerMustFree := false）

這將執行類似於以下的JOIN SELECT語句：

select p.*, c.*, s.*
from Product p, Category c, Categories cc, Size s, Sizes ss

這個函數允許用戶準備和執行複雜的JOIN查詢，同時自動處理 TOrmMany關係。通過這種方式，用戶可以方便地獲取相關聯的數據，併在應用程式中進行進一步處理。此函數還提供了參數化查詢的功能，增強了查詢的靈活性和安全性。