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():

Код MySQL Shell JavaScript

// 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);
}

Код MySQL Shell Python

# 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()

Код Node.js JavaScript

// Use the collection 'my_collection'
var myColl = db.getCollection('my_collection');

// Find a single document that has a field 'name' that starts with 'L'
myColl
  .find('name like :name')
  .bind('name', 'L%')
  .limit(1)
  .execute(function (doc) {
    console.log(doc);
  })
  .then(function () {
    // handle details
  });

// Get all documents with a field 'name' that starts with 'L'
myColl
  .find('name like :name')
  .bind('name', 'L%')
  .execute(function (doc) {
    console.log(doc);
  })
  .then(function () {
    // handle details
  });

Код C#

// 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();

Console.WriteLine(docs.FetchOne());

// Get all documents with a field "name" that starts with "L"
docs = myColl.Find("name like :param")
.Bind("param", "L%").Execute();

while (docs.Next())
{
    Console.WriteLine(docs.Current);
}

Код Python

# Use the collection 'my_collection'
my_coll = my_schema.get_collection('my_collection')

# Find a single document that has a field 'name' that starts with 'L'
docs = my_coll.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 = my_coll.find('name like :param').bind('param', 'L%').execute()

doc = docs.fetch_one()
print(doc)

Код Java

// Use the collection 'my_collection'
Collection myColl = db.getCollection("my_collection");

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

System.out.println(docs.fetchOne());

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

while (docs.hasNext()) {
    DbDoc myDoc = docs.next();
    System.out.println(myDoc);
}

Код C++

// Use the collection 'my_collection'
Collection myColl = db.getCollection("my_collection");

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

cout << docs.fetchOne() << endl;

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

DbDoc myDoc;
while ((myDoc = docs.fetchOne()))
{
  cout << myDoc << endl;
}

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