4.3.2 Collection.find()

Функция find(SearchConditionStr) предназначена для поиска документов в коллекции, аналогично оператору `SELECT` в базе данных SQL. Она принимает строку условия поиска (SearchConditionStr) в качестве параметра для указания документов, которые должны быть возвращены из базы данных. Функция execute() запускает фактическое выполнение операции find().

Строка условия поиска (SearchConditionStr) может иметь один из следующих форматов:

Если строка условия поиска (SearchConditionStr) не указана, операция find() возвращает все документы в коллекции.
```
// Get a collection
var myColl = session.getSchema("world_x").getCollection("countryinfo");
// To return all documents in world_x:
myColl.find().execute();
```
Наиболее распространённый формат для строки условия поиска (SearchConditionStr) выглядит следующим образом:
```
JSON-path [ operator { value | JSON-path} ] 
```
Ниже приведены объяснения различных частей строки условия поиска (SearchConditionStr):
- JSON-path: JSON-путь идентифицирует элемент в документе JSON; см. для получения подробностей. Вот краткое описание синтаксиса JSON-путей:
  - JSON-путь начинается со скоупа: в реализации документов JSON в MySQL скоуп пути всегда является документом, над которым выполняется операция, представленным как $, который всегда подразумевается неявно, поэтому его можно опустить в большинстве случаев; например, путь $.geography.Region эквивалентен geography.Region.
    
    Примечание
    
    В некоторых случаях $ нельзя опустить; например:
    
    Когда используется символ подстановки ** (например, find("$**.b1"); см. обсуждение символов подстановки ниже),
    
    Когда JSON-путь содержит только строковую литерал, если $ опущено (например, find("$.'country_name'") для поиска всех документов, имеющих поле country name).
  - После скоупа путь состоит из одного или нескольких звеньев пути. Звено пути переходит с одного уровня дерева JSON на следующий, а последовательные пути разделяются точкой (.). Например: myColl.find("geography.Continent = 'Africa'") находит все документы, имеющие значение Africa для поля Continent в поле geography.
  - Элементы в массивах представлены как [N], где N - это индекс массива, который должен быть неотрицательным целым числом.
    
    myColl.add({ name:'John', favorNums: [1, 3, 5, 7, 9] }).execute(); myColl.find("favorNums[0] = 1").execute(); //Returns the document just added }
- Символы подстановки * и ** могут использоваться в JSON-путях следующим образом:
  - object.* представляет значения всех членов под членом object. Например, в коллекции countryinfo в схеме образца world_x, geography.* представляет все члены под объектом geography, а myColl.find("'Africa' in geography.*") возвращает все документы, имеющие значение Africa в любом из членов под geography.
  - array[*] представляет значения всех элементов в массиве. Например:
    
    myColl.add({ name:'John', favorNums: [1, 3, 5, 7, 9] }).execute(); myColl.add({ name:'Jane', favorNums: [2, 4, 6, 8, 10] }).execute(); myColl.find("1 in favorNums[*]").execute(); //Returns the first document added above myColl.find("2 in favorNums[*]").execute(); //Returns the second document added above }
  - [prefix]**suffix представляет все пути под документом prefix, которые заканчиваются на suffix, независимо от глубины пути. Следующие примеры иллюстрируют, как ** можно использовать для возвращения различных результатов:
    
    mysql-js> myColl.find().execute(); { "a": "bar", "b": { "b1": 6, "b2": 7, "b3": { "b1": 99, "b2": 98, "b3": { "b1": 999, "b2": 998 } } }, "_id": "000061313aa10000000000000001" } { "a": "baz", "b": { "b1": 1, "b2": 7 }, "_id": "000061313aa10000000000000002" } { "a": "bbr", "c": 37, "_id": "0000613247ed0000000000000001" } 3 documents in set (0.0007 sec) mysql-js> myColl.find("$**.b2").execute(); { "a": "bar", "b": { "b1": 6, "b2": 7, "b3": { "b1": 99, "b2": 98, "b3": { "b1": 999, "b2": 998 } } }, "_id": "000061313aa10000000000000001" } { "a": "baz", "b": { "b1": 1, "b2": 7 }, "_id": "000061313aa10000000000000002" } 2 documents in set, 1 warning (0.0008 sec) ... mysql-js> myColl.find("$**.b3**.b2").execute(); { "a": "bar", "b": { "b1": 6, "b2": 7, "b3": { "b1": 99, "b2": 98, "b3": { "b1": 999, "b2": 998 } } }, "_id": "000061313aa10000000000000001" } 1 document in set, 1 warning (0.0011 sec) ...
    
    При использовании символа подстановки ** действуют следующие требования:
    
    prefix должен быть $ или элементом, который сам является документом.
    
    suffix должно быть звеном пути и всегда требуется (то есть выражение пути не может заканчиваться на **).
    
    Выражение пути не может содержать последовательность ***.
- value - это значение, которое должно быть сравнено с элементом на JSON-path. Символы подстановки % и _ могут использоваться в value с оператором LIKE, как и в операторе `WHERE` в MySQL. Например:
```
myColl.find("Name LIKE 'Austra%'")
myColl.find("geography.Continent LIKE 'Asi_'")
```
- operator: В строке условия поиска (SearchConditionStr) можно использовать следующие операторы: OR (||), AND (&&), XOR, IS, NOT, BETWEEN, IN, LIKE, OVERLAPS, !=, <>, >, >=, <, <=, &, |, <<, >>, +, -, *, /, ~ и %. Вот несколько примеров использования операторов:
```
myColl.find("Name = 'Australia'")
myColl.find("demographics.Population >= 1000000" )
myColl.find("demographics.LifeExpectancy BETWEEN 50  AND 60")
myColl.find("government.HeadOfState = 'Elizabeth II' AND geography.Region = 'Caribbean'")
```
  Если не указан оператор и последующий JSON-путь, find() возвращает все документы, для которых JSON-путь указывает на некоторые непустые элементы. Например:
```
myColl.find("demographics.Population" ).execute();
```
  Возвращает все документы, имеющие элемент demographics.Population:
```
{
    "GNP": 828,
    "_id": "00005de917d80000000000000000",
    "Code": "ABW",
    "Name": "Aruba",
    "IndepYear": null,
    "geography": {
        "Region": "Caribbean",
        "Continent": "North America",
        "SurfaceArea": 193
    },
    "government": {
        "HeadOfState": "Beatrix",
        "GovernmentForm": "Nonmetropolitan Territory of The Netherlands"
    },
    "demographics": {
        "Population": 103000,
        "LifeExpectancy": 78.4000015258789
    }
}
{
    "GNP": 5976,
    "_id": "00005de917d80000000000000001",
...
232 documents in set, 1 warning (0.0013 sec)
Warning (code 3986): Evaluating a JSON value in SQL boolean context does an implicit comparison against JSON integer 0;
if this is not what you want, consider converting JSON to an SQL numeric type with JSON_VALUE RETURNING
```
  Используйте оператор IN в строке условия поиска (SearchConditionStr), чтобы проверить значение среди всех элементов, охватываемых символом подстановки:
```
mysql-js> myColl.find("$**.b1").execute();
{
    "a": "bar",
    "b": {
        "b1": 6,
        "b2": 7,
        "b3": {
            "b1": 99,
            "b2": 98,
            "b3": {
                "b1": 999,
                "b2": 998
            }
        }
    },
    "_id": "000061313aa10000000000000001"
}
{
    "a": "baz",
    "b": {
        "b1": 1,
        "b2": 7
    },
    "_id": "000061313aa10000000000000002"
}
2 documents in set, 1 warning (0.0012 sec)
...
mysql-js> myColl.find("99 IN $**.b1").execute();
{
    "a": "bar",
    "b": {
        "b1": 6,
        "b2": 7,
        "b3": {
            "b1": 99,
            "b2": 98,
            "b3": {
                "b1": 999,
                "b2": 998
            }
        }
    },
    "_id": "000061313aa10000000000000001"
}
1 document in set (0.0016 sec)
...
```
  Оператор OVERLAPS сравнивает два фрагмента JSON и возвращает true (1), если два фрагмента имеют общие значения в любой паре ключ-значение или элементе массива. Например:
```
mysql-js> myColl.find("list").execute();
{
    "_id": "1",
    "list": [
        1,
        4
    ]
}
{
    "_id": "2",
    "list": [
        4,
        7
    ]
}
2 documents in set, 1 warning (0.0010 sec)
mysql-js> myColl.find("[1,2,3] OVERLAPS $.list")
{
    "_id": "1",
    "list": [
        1,
        4
    ]
}
1 document in set (0.0006 sec)
```

Несколько методов, таких как fields(), sort() и limit(), могут быть объединены с функцией find(), чтобы дополнительно уточнить результат. Например:

myColl.find("Name LIKE 'Austra%'").fields("Code")
myColl.find("geography.Continent LIKE 'A%'").limit(10)

Также поддерживается привязка параметров с использованием bind(). Следующий пример иллюстрирует использование bind() с find():

# Use the collection 'my_collection'
myColl = db.get_collection('my_collection')

# Find a single document that has a field 'name' that starts with 'L'
docs = myColl.find('name like :param').limit(1).bind('param', 'L%').execute()

print(docs.fetch_one())

# Get all documents with a field 'name' that starts with 'L'
docs = myColl.find('name like :param').bind('param','L%').execute()

myDoc = docs.fetch_one()
while myDoc:
  print(myDoc)
  myDoc = docs.fetch_one()

См. также CollectionFindFunction для синтаксиса find() в EBNF.