0 追蹤者

介面 yii\db\ActiveQueryInterface

所有類別 | 方法
繼承自yii\db\QueryInterface
實作於yii\db\ActiveQuery
自版本起可用2.0
原始碼 https://github.com/yiisoft/yii2/blob/master/framework/db/ActiveQueryInterface.php

ActiveQueryInterface 定義了 active record 查詢類別應實作的通用介面。

這些方法適用於回傳 active record 的一般查詢，以及關聯式查詢，在關聯式查詢中，查詢代表兩個 active record 類別之間的關聯，並且僅回傳相關的記錄。

實作此介面的類別也應使用 yii\db\ActiveQueryTrait 和 yii\db\ActiveRelationTrait。

公開方法

隱藏繼承的方法

方法 描述 定義於
addOrderBy() 為查詢新增額外的 ORDER BY 欄位。 yii\db\QueryInterface
all() 執行查詢並將所有結果作為陣列回傳。 yii\db\QueryInterface
andFilterWhere() 在現有的 WHERE 條件中加入額外的條件，並忽略空的參數。 yii\db\QueryInterface
andWhere() 在現有的 WHERE 條件中加入額外的條件。 yii\db\QueryInterface
asArray() 設定 asArray() 屬性。 yii\db\ActiveQueryInterface
count() 回傳記錄的數量。 yii\db\QueryInterface
emulateExecution() 設定是否模擬查詢執行，防止與資料儲存進行任何互動。 yii\db\QueryInterface
exists() 回傳一個值，指示查詢結果是否包含任何資料列。 yii\db\QueryInterface
filterWhere() 設定查詢的 WHERE 部分，並忽略空的參數。 yii\db\QueryInterface
findFor() 為指定的 primary 記錄尋找相關的記錄。 yii\db\ActiveQueryInterface
indexBy() 設定 indexBy() 屬性。 yii\db\ActiveQueryInterface
limit() 設定查詢的 LIMIT 部分。 yii\db\QueryInterface
offset() 設定查詢的 OFFSET 部分。 yii\db\QueryInterface
one() 執行查詢並返回單一結果列。 yii\db\ActiveQueryInterface
orFilterWhere() 在現有的 WHERE 條件中加入額外的條件，並忽略空的參數。 yii\db\QueryInterface
orWhere() 在現有的 WHERE 條件中加入額外的條件。 yii\db\QueryInterface
orderBy() 設定查詢的 ORDER BY 部分。 yii\db\QueryInterface
via() 指定與 junction table 關聯的關聯，用於關聯式查詢。 yii\db\ActiveQueryInterface
where() 設定查詢的 WHERE 部分。 yii\db\QueryInterface
with() 指定此查詢應執行的關聯。 yii\db\ActiveQueryInterface

方法詳情

隱藏繼承的方法

addOrderBy() public abstract method

定義於： yii\db\QueryInterface::addOrderBy()

為查詢新增額外的 ORDER BY 欄位。

另請參閱 orderBy()。

public abstract $this addOrderBy ( $columns )
$columns string|array

要排序的欄位（以及排序方向）。欄位可以指定為字串 (例如 "id ASC, name DESC") 或陣列 (例如 ['id' => SORT_ASC, 'name' => SORT_DESC])。此方法將自動為欄位名稱加上引號，除非欄位包含括號（表示欄位包含 DB 表達式）。
return $this

查詢物件本身

 

                public function addOrderBy($columns);
all() public abstract method

定義於： yii\db\QueryInterface::all()

執行查詢並將所有結果作為陣列回傳。

public abstract array all ( $db = null )
$db yii\db\Connection|null

用於執行查詢的資料庫連線。如果未提供此參數，將使用 db 應用程式元件。
return array

查詢結果。如果查詢沒有結果，將返回一個空陣列。

 

                public function all($db = null);
andFilterWhere() public abstract method

定義於： yii\db\QueryInterface::andFilterWhere()

在現有的 WHERE 條件中加入額外的條件，並忽略空的參數。

新條件和現有條件將使用 'AND' 運算符號連接。

另請參閱

public abstract $this andFilterWhere ( array $condition )
$condition array

新的 WHERE 條件。請參閱 where() 以了解如何指定此參數。
return $this

查詢物件本身

 

                public function andFilterWhere(array $condition);
andWhere() public abstract method

定義於： yii\db\QueryInterface::andWhere()

在現有的 WHERE 條件中加入額外的條件。

新條件和現有條件將使用 'AND' 運算符號連接。

另請參閱

public abstract $this andWhere ( $condition )
$condition array

新的 WHERE 條件。請參閱 where() 以了解如何指定此參數。
return $this

查詢物件本身

 

                public function andWhere($condition);
asArray() public abstract method

設定 asArray() 屬性。

public abstract $this asArray ( $value = true )
$value boolean

是否以陣列形式而不是 Active Record 的形式返回查詢結果。
return $this

查詢物件本身

 

                public function asArray($value = true);
count() public abstract method

定義於： yii\db\QueryInterface::count()

回傳記錄的數量。

public abstract integer|string|null count ( $q = '*', $db = null )
$q string

COUNT 表達式。預設為 '*'。
$db yii\db\Connection|null

用於執行查詢的資料庫連線。如果未提供此參數，將使用 db 應用程式元件。
return integer|string|null

記錄數量。

 

                public function count($q = '*', $db = null);
emulateExecution() public abstract method (自版本 2.0.11 起可用)

定義於： yii\db\QueryInterface::emulateExecution()

設定是否模擬查詢執行，防止與資料儲存進行任何互動。

在此模式啟用後，返回查詢結果的方法，例如 one()、all()、exists() 等，將返回空值或 false 值。 如果您的程式邏輯表明查詢不應返回任何結果，例如在您設定類似 0=1 的 false where 條件時，您應該使用此方法。

public abstract $this emulateExecution ( $value = true )
$value boolean

是否阻止查詢執行。
return $this

查詢物件本身。

 

                public function emulateExecution($value = true);
exists() public abstract method

定義於： yii\db\QueryInterface::exists()

回傳一個值，指示查詢結果是否包含任何資料列。

public abstract boolean exists ( $db = null )
$db yii\db\Connection|null

用於執行查詢的資料庫連線。如果未提供此參數，將使用 db 應用程式元件。
return boolean

查詢結果是否包含任何資料列。

 

                public function exists($db = null);
filterWhere() public abstract method

定義於： yii\db\QueryInterface::filterWhere()

設定查詢的 WHERE 部分，並忽略空的參數。

另請參閱

public abstract $this filterWhere ( array $condition )
$condition array

應放入 WHERE 部分的條件。請參閱 where() 以了解如何指定此參數。
return $this

查詢物件本身

 

                public function filterWhere(array $condition);
findFor() public abstract method

為指定的 primary 記錄尋找相關的記錄。

當 ActiveRecord 的關聯以延遲方式存取時，會調用此方法。

public abstract mixed findFor ( $name, $model )
$name string

關聯名稱
$model yii\db\ActiveRecordInterface

主要模型
return mixed

相關記錄

 

                public function findFor($name, $model);
indexBy() public abstract method

設定 indexBy() 屬性。

public abstract $this indexBy ( $column )
$column string|callable

查詢結果應依其索引的欄位名稱。 這也可以是一個可調用的 (例如匿名函式)，它根據給定的列或模型資料返回索引值。 可調用的簽名應為

// $model is an AR instance when `asArray` is false,
// or an array of column values when `asArray` is true.
function ($model)
{
    // return the index value corresponding to $model
}
return $this

查詢物件本身

 

                public function indexBy($column);
limit() public abstract method

定義於： yii\db\QueryInterface::limit()

設定查詢的 LIMIT 部分。

public abstract $this limit ( $limit )
$limit integer|null

限制。 使用 null 或負值來禁用限制。
return $this

查詢物件本身

 

                public function limit($limit);
offset() public abstract method

定義於： yii\db\QueryInterface::offset()

設定查詢的 OFFSET 部分。

public abstract $this offset ( $offset )
$offset integer|null

偏移量。 使用 null 或負值來禁用偏移量。
return $this

查詢物件本身

 

                public function offset($offset);
one() public abstract method

執行查詢並返回單一結果列。

public abstract yii\db\ActiveRecordInterface|array|null one ( $db = null )
$db yii\db\Connection|null

用於建立 DB 命令的 DB 連線。 如果 null，將使用 modelClass 返回的 DB 連線。
return yii\db\ActiveRecordInterface|array|null

單一查詢結果列。 根據 asArray() 的設定，查詢結果可以是陣列或 ActiveRecord 物件。 如果查詢沒有結果，將返回 null。

 

                public function one($db = null);
orFilterWhere() public abstract method

定義於： yii\db\QueryInterface::orFilterWhere()

在現有的 WHERE 條件中加入額外的條件，並忽略空的參數。

新條件和現有條件將使用 'OR' 運算符號連接。

另請參閱

public abstract $this orFilterWhere ( array $condition )
$condition array

新的 WHERE 條件。請參閱 where() 以了解如何指定此參數。
return $this

查詢物件本身

 

                public function orFilterWhere(array $condition);
orWhere() public abstract method

定義於： yii\db\QueryInterface::orWhere()

在現有的 WHERE 條件中加入額外的條件。

新條件和現有條件將使用 'OR' 運算符號連接。

另請參閱

public abstract $this orWhere ( $condition )
$condition array

新的 WHERE 條件。請參閱 where() 以了解如何指定此參數。
return $this

查詢物件本身

 

                public function orWhere($condition);
orderBy() public abstract method

定義於： yii\db\QueryInterface::orderBy()

設定查詢的 ORDER BY 部分。

另請參閱 addOrderBy()。

public abstract $this orderBy ( $columns )
$columns string|array

要排序的欄位（以及排序方向）。欄位可以指定為字串 (例如 "id ASC, name DESC") 或陣列 (例如 ['id' => SORT_ASC, 'name' => SORT_DESC])。此方法將自動為欄位名稱加上引號，除非欄位包含括號（表示欄位包含 DB 表達式）。
return $this

查詢物件本身

 

                public function orderBy($columns);
via() public abstract method

指定與 junction table 關聯的關聯，用於關聯式查詢。

public abstract $this via ( $relationName, callable $callable = null )
$relationName string

關聯名稱。 這指的是在關聯的 primaryModel 中宣告的關聯。
$callable callable|null

用於自訂與 junction table 關聯的關聯的 PHP 回調。 其簽名應為 function($query)，其中 $query 是要自訂的查詢。
return $this

關聯物件本身。

 

                public function via($relationName, callable $callable = null);
where() public abstract method

定義於： yii\db\QueryInterface::where()

設定查詢的 WHERE 部分。

以陣列形式指定的 $condition 可以是以下兩種格式之一

  • 雜湊格式：['column1' => value1, 'column2' => value2, ...]
  • 運算符號格式：[operator, operand1, operand2, ...]

雜湊格式的條件通常表示以下 SQL 表達式：column1=value1 AND column2=value2 AND ...。 如果值是陣列，將生成 IN 表達式。 如果值是 null，則將在生成的表達式中使用 IS NULL。 以下是一些範例

  • ['type' => 1, 'status' => 2] 生成 (type = 1) AND (status = 2)。
  • ['id' => [1, 2, 3], 'status' => 2] 生成 (id IN (1, 2, 3)) AND (status = 2)。
  • ['status' => null] 生成 status IS NULL。

運算符號格式的條件根據指定的運算符號生成 SQL 表達式，可以是以下之一

  • and：運算元應使用 AND 連接在一起。 例如，['and', 'id=1', 'id=2'] 將生成 id=1 AND id=2。 如果運算元是陣列，它將使用此處描述的規則轉換為字串。 例如，['and', 'type=1', ['or', 'id=1', 'id=2']] 將生成 type=1 AND (id=1 OR id=2)。 該方法不會執行任何引號或轉義。

  • or：與 and 運算符號類似，不同之處在於運算元使用 OR 連接。 例如，['or', ['type' => [7, 8, 9]], ['id' => [1, 2, 3]]] 將生成 (type IN (7, 8, 9) OR (id IN (1, 2, 3)))。

  • not：這將僅採用一個運算元，並通過在查詢字串前加上 NOT 來構建其否定。 例如 ['not', ['attribute' => null]] 將產生條件 NOT (attribute IS NULL)。

  • between：運算元 1 應為欄位名稱，運算元 2 和 3 應為欄位所在的範圍的起始值和結束值。 例如，['between', 'id', 1, 10] 將生成 id BETWEEN 1 AND 10。

  • not between：與 between 類似，不同之處在於生成的條件中 BETWEEN 替換為 NOT BETWEEN。

  • in：運算元 1 應為欄位或 DB 表達式，運算元 2 應為表示欄位或 DB 表達式應在其中的值範圍的陣列。 例如，['in', 'id', [1, 2, 3]] 將生成 id IN (1, 2, 3)。 該方法將正確地引用欄位名稱並轉義範圍中的值。

    要建立複合 IN 條件，您可以對欄位名稱和值使用陣列，其中值按欄位名稱索引：['in', ['id', 'name'], [['id' => 1, 'name' => 'foo'], ['id' => 2, 'name' => 'bar']] ]。

    您還可以指定用於獲取 IN 條件的值的子查詢：['in', 'user_id', (new Query())->select('id')->from('users')->where(['active' => 1])]

  • not in：與 in 運算符號類似，不同之處在於生成的條件中 IN 替換為 NOT IN。

  • like：運算元 1 應為欄位或 DB 表達式，運算元 2 應為表示欄位或 DB 表達式應類似的值的字串或陣列。 例如，['like', 'name', 'tester'] 將生成 name LIKE '%tester%'。 當值範圍作為陣列給出時，將生成多個 LIKE 謂詞並使用 AND 連接。 例如，['like', 'name', ['test', 'sample']] 將生成 name LIKE '%test%' AND name LIKE '%sample%'。 該方法將正確地引用欄位名稱並轉義值中的特殊字元。 有時，您可能想要自己將百分號字元添加到匹配值中，您可以提供第三個運算元 false 來執行此操作。 例如，['like', 'name', '%tester', false] 將生成 name LIKE '%tester'。

  • or like：與 like 運算符號類似，不同之處在於當運算元 2 是陣列時，OR 用於連接 LIKE 謂詞。

  • not like：與 like 運算符號類似，不同之處在於生成的條件中 LIKE 替換為 NOT LIKE。

  • or not like：與 not like 運算符號類似，不同之處在於 OR 用於連接 NOT LIKE 謂詞。

  • exists：運算元 1 是用於構建 EXISTS 條件的查詢物件。 例如 ['exists', (new Query())->select('id')->from('users')->where(['active' => 1])] 將產生以下 SQL 表達式：EXISTS (SELECT "id" FROM "users" WHERE "active"=1)。

  • not exists：與 exists 運算符號類似，不同之處在於生成的條件中 EXISTS 替換為 NOT EXISTS。

  • 此外，您可以按如下方式指定任意運算符號：['>=', 'id', 10] 的條件將產生以下 SQL 表達式：id >= 10。

請注意，此方法將覆蓋任何現有的 WHERE 條件。 您可能想要改用 andWhere() 或 orWhere()。

另請參閱

public abstract $this where ( $condition )
$condition array

應放入 WHERE 部分的條件。
return $this

查詢物件本身

 

                public function where($condition);
with() public abstract method

指定此查詢應執行的關聯。

此方法的參數可以是單個或多個字串，也可以是關係名稱的單個陣列以及用於自訂關係的可選回調。

關係名稱可以參考 modelClass 中定義的關係，或代表相關記錄關係的子關係。 例如，orders.address 表示在與 orders 關係對應的模型類別中定義的 address 關係。

以下是一些用法範例

// find customers together with their orders and country
Customer::find()->with('orders', 'country')->all();
// find customers together with their orders and the orders' shipping address
Customer::find()->with('orders.address')->all();
// find customers together with their country and orders of status 1
Customer::find()->with([
    'orders' => function (\yii\db\ActiveQuery $query) {
        $query->andWhere('status = 1');
    },
    'country',
])->all();
public abstract $this with ( )
return $this

查詢物件本身

 

                public function with();