public static method

The find method allows you to retrieve data from the connected data source.


Posts::find('all'); // returns all records
Posts::find('count'); // returns a count of all records

// The first ten records that have `'author'` set to `'Bob'`.
Posts::find('all', [
    'conditions' => ['author' => 'Bob'],
    'limit' => 10

// First record where the id matches 23.
Posts::find('first', [
    'conditions' => ['id' => 23]


// Shorthand for find first by primary key.

// Also works with objects.
Posts::find(new ObjectId(23));


  • string|object|integer $type

    The name of the finder to use. By default the following finders are available. Custom finders can be added via Model::finder().

    • 'all': Returns all records matching the conditions.
    • 'first': Returns the first record matching the conditions.
    • 'count': Returns an integer count of all records matching the conditions. When using Database adapter, you can specify the field to count on via fields, when multiple fields are given does a count on all fields ('*').
    • 'list': Returns a one dimensional array, where the key is the (primary)p key and the value the title of the record (the record must have a 'title' field). A result may look like: [1 => 'Foo', 2 => 'Bar'].

    Instead of the name of a finder, also supports shorthand usage with an object or integer as the first parameter. When passed such a value it is equal to Model::find('first', ['conditions' => ['<key>' => <value>]]).

    Note: When an undefined finder is tried to be used, the method will not error out, but fallback to the 'all' finder.

  • array $options

    Options for the query. Common options accepted are:

    • 'conditions' array: The conditions for the query i.e. ['is_published' => true].
    • 'fields' array|null: The fields that should be retrieved. When set to null or '*' and by default, uses all fields. To optimize query performance, limit the fields to just the ones actually needed.
    • 'order' array|string: The order in which the data will be returned, i.e. 'created ASC' sorts by created date in ascending order. To sort by multiple fields use the array syntax ['title' => 'ASC', 'id' => 'ASC'].
    • 'limit' integer: The maximum number of records to return.
    • 'page' integer: Allows to paginate data sets. Specifies the page of the set together with the limit option specifying the number of records per page. The first page starts at 1. Equals limit * offset.
    • 'with' array: Relationship names to be included in the query. Also supported are:
    • 'offset' integer
    • 'having' array|string
    • 'group' array|string
    • 'joins' array



The result/s of the find. Actual result depends on the finder being used. Most often this is an instance of lithium\data\Collection or lithium\data\Entity.


Allows to execute logic before querying (i.e. for rewriting of $options) or after i.e. for caching results.


	public static function find($type, array $options = []) {
		$self = static::object();

		if (is_object($type) || !isset($self->_finders[$type])) {
			$options['conditions'] = static::key($type);
			$type = 'first';

		$options += (array) $self->_query;
		$meta = ['meta' => $self->_meta, 'name' => get_called_class()];
		$params = compact('type', 'options');

		$implementation = function($params) use ($self, $meta) {
			$options = $params['options'] + ['type' => 'read', 'model' => $meta['name']];
			$query = Libraries::instance(null, 'query', $options, $self->_classes);

			return static::connection()->read($query, $options);
		if (isset($self->_finders[$type])) {
			$finder = $self->_finders[$type];

			$implementation = function($params) use ($finder, $implementation) {
				return $finder($params, $implementation);
		return Filters::run(get_called_class(), __FUNCTION__, $params, $implementation);