4.3.2 Collection.find()

Функция find(SearchConditionStr) предназначена для поиска документов в коллекции, аналогично оператору 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, как и в предложении MySQL WHERE. Например:
```
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'
var myColl = db.getCollection('my_collection');

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

print(docs.fetchOne());

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

var myDoc;
while (myDoc = docs.fetchOne()) {
  print(myDoc);
}

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