Выполнение операции сравнения слияния с конфигурацией из файла приведет к

Обновлено: 02.07.2024

Загрузка файлов конфигурации на устройство полезна для загрузки частей файлов конфигурации, которые могут быть общими для многих устройств в сети.

Примеры загрузки конфигурации из файла или терминала

Вы можете создать файл, содержащий данные конфигурации для устройства Juniper Networks, скопировать файл на локальное устройство, а затем загрузить его в интерфейс командной строки. После того, как вы загрузили файл, вы можете зафиксировать его, чтобы активировать конфигурацию на устройстве, или вы можете отредактировать конфигурацию в интерактивном режиме с помощью интерфейса командной строки и зафиксировать конфигурацию позже.

Вы также можете создать конфигурацию, набрав ее в терминале, а затем загрузить конфигурацию. Загрузка конфигурации из терминала полезна, когда вы вырезаете существующие части конфигурации и вставляете их в другое место в конфигурации.

Чтобы загрузить существующий файл конфигурации, расположенный на устройстве, используйте команду режима загрузки конфигурации:

Чтобы загрузить конфигурацию из терминала, используйте следующую версию команды режима загрузки конфигурации. Нажмите Ctrl-d, чтобы завершить ввод.

Чтобы заменить всю конфигурацию, укажите параметр переопределения на любом уровне иерархии. Операция переопределения загрузки полностью заменяет текущую конфигурацию кандидата загружаемым файлом. Таким образом, если вы сохранили полную конфигурацию, вы используете эту опцию.

Операция переопределения отбрасывает текущую конфигурацию кандидата и загружает конфигурацию в имени файла или конфигурацию, которую вы вводите на терминале. Когда вы используете параметр переопределения и фиксируете конфигурацию, все системные процессы повторно анализируют конфигурацию.

Чтобы заменить части конфигурации, укажите параметр замены. Операция замены загрузки ищет теги replace:, которые вы добавили в загруженный файл. Затем операция заменяет эти части конфигурации-кандидата тем, что указано после тега. Это полезно, когда вы хотите больше контролировать то, что именно изменяется. Чтобы эта операция работала, вы должны включить теги replace: в файл или конфигурацию, которую вы вводите в терминале. Программное обеспечение ищет теги replace:, удаляет существующие операторы с тем же именем, если они есть, и заменяет их входящей конфигурацией. Если оператора с таким именем не существует, операция замены добавляет в конфигурацию операторы, помеченные тегом replace:.

Если в операции переопределения или слияния вы указываете файл или вводите текст, который содержит теги replace:, теги replace: игнорируются. В этом сценарии операция переопределения или слияния имеет приоритет и выполняется.

Если вы выполняете операцию замены и в указанном файле отсутствуют теги replace:, операция замены выполняется как операция слияния. Операция замены также выполняется как операция слияния, если в тексте, который вы вводите, отсутствуют теги replace:. Эта информация может быть полезна, если вы запускаете автоматизированные сценарии и не можете заранее знать, должны ли сценарии выполнять операцию замены или операцию слияния. Сценарии могут использовать операцию замены в любом случае.

Операция загрузки слияния объединяет конфигурацию из сохраненного файла или терминала с существующей конфигурацией-кандидатом. Эта информация полезна, если вы добавляете новые разделы конфигурации. Например, предположим, что вы добавляете конфигурацию BGP на уровень иерархии [редактировать протоколы], где раньше не было конфигурации BGP. Вы можете использовать операцию слияния загрузки, чтобы объединить входящую конфигурацию с существующей конфигурацией-кандидатом. Если существующая конфигурация и входящая конфигурация содержат конфликтующие операторы, операторы входящей конфигурации переопределяют операторы в существующей конфигурации.

Чтобы заменить только те части конфигурации, которые изменились, укажите параметр обновления на любом уровне иерархии. Операция обновления загрузки сравнивает конфигурацию-кандидата и новые данные конфигурации. Эта операция изменяет только те части конфигурации-кандидата, которые отличаются от новой конфигурации. Вы можете использовать эту операцию, например, если существует существующая конфигурация BGP, а загружаемый файл каким-то образом изменяет ее.

Параметры слияния , переопределения и обновления поддерживают загрузку данных конфигурации в формате нотации объектов JavaScript (JSON). При загрузке данных конфигурации в формате JSON необходимо указать параметр json в команде.

Чтобы изменить часть конфигурации с помощью файла исправления, укажите параметр исправления. Операция load patch загружает файл или ввод терминала, который содержит изменения конфигурации.Во-первых, на устройстве, на котором уже есть изменения конфигурации, введите команду show | команда сравнения для вывода различий между двумя конфигурациями. Затем вы можете загрузить различия на другом устройстве. Преимущество команды load patch заключается в том, что она избавляет вас от необходимости копировать фрагменты с разных уровней иерархии в текстовый файл перед их загрузкой на целевое устройство. Это может помочь сэкономить время, если вы настраиваете несколько устройств с одинаковыми параметрами. Например, предположим, что вы настраиваете политику маршрутизации на маршрутизаторе 1 и хотите реплицировать конфигурацию политики на маршрутизаторах 2, 3 и 4. Вы можете использовать операцию исправления загрузки.

В этом примере вы сначала запускаете шоу | команда сравнения.

Продолжая этот пример, вы копируете вывод команды show | сравните команду с буфером обмена, обязательно включив уровни иерархии. На маршрутизаторе Router2, Router3 и Router4 вы вводите load patch terminal и вставляете вывод. Затем вы нажимаете Enter и нажимаете Ctrl-d, чтобы завершить операцию. Если ввод исправления указывает другие значения для существующего оператора, ввод исправления переопределяет существующий оператор.

Чтобы использовать параметры слияния, замены, установки или обновления без указания полного уровня иерархии, укажите относительный параметр. Этот параметр загружает входящую конфигурацию относительно вашей текущей точки редактирования в иерархии конфигурации.

Чтобы загрузить конфигурацию, содержащую команды режима установки конфигурации, укажите параметр установки. Эта опция выполняет инструкции по настройке строка за строкой, поскольку они хранятся в файле или с терминала. Инструкции могут содержать любую команду режима конфигурации, такую как set , edit , exit и top .

Чтобы скопировать файл конфигурации из другой сетевой системы на локальный маршрутизатор, вы можете использовать утилиты SSH и Telnet, как описано в CLI Explorer.

Если вы работаете в среде Common Criteria, сообщения системного журнала создаются при каждом изменении атрибута секрета (например, при изменении пароля или изменении общего секрета RADIUS). Эти изменения регистрируются во время следующих операций загрузки конфигурации:

Как работает кодировка символов на устройствах Juniper Networks

Данные конфигурации ОС Junos и выходные данные рабочих команд могут содержать символы, отличные от ASCII, которые не входят в 7-битный набор символов ASCII. При отображении рабочих данных или данных конфигурации в определенных форматах или в рамках определенного типа сеанса программное обеспечение экранирует и кодирует эти символы. Программное обеспечение экранирует или кодирует символы, используя эквивалентную ссылку на десятичный символ UTF-8.

CLI пытается отобразить любые символы, отличные от ASCII, в данных конфигурации, созданных в текстовом формате, наборе или формате JSON. CLI также пытается отобразить эти символы в выводе команды, который создается в текстовом формате. В исключительных случаях CLI вместо этого отображает ссылку на десятичный символ UTF-8. (Исключениями являются данные конфигурации в формате XML и выходные данные команд в формате XML или JSON.) В сеансах протоколов NETCONF и Junos XML вы увидите аналогичный результат, если запросите данные конфигурации или выходные данные команды, которые содержат символы, отличные от ASCII. В этом случае сервер возвращает эквивалентную ссылку на десятичный символ UTF-8 для этих символов для всех форматов.

Например, предположим, что на устройстве настроена следующая учетная запись пользователя, которая содержит строчную латинскую букву n с тильдой (ñ).

Когда вы отображаете результирующую конфигурацию в текстовом формате, интерфейс командной строки печатает соответствующий символ.

Когда вы загружаете данные конфигурации на устройство, вы можете загружать символы, отличные от ASCII, используя их эквивалентные ссылки на десятичные символы UTF-8.

О задании выражений и идентификаторов

В этом разделе приведены подробные сведения об операторах контейнера CLI и листовых операторах, чтобы вы знали, как указать их при создании файлов конфигурации ASCII. В этом разделе также описывается, как интерфейс командной строки выполняет проверку типов, чтобы убедиться, что введенные вами данные имеют правильный формат.

Определение выражений

Утверждения отображаются одним из двух способов: с фигурными скобками (< >) или без них:

Имя оператора и идентификатор с одним или несколькими операторами более низкого уровня, заключенными в фигурные скобки:

Имя оператора, идентификатор и один идентификатор:

Имя оператора — это имя оператора. Имя-идентификатора — это имя или другая строка, которая однозначно идентифицирует экземпляр оператора. Вы используете идентификатор, когда оператор может быть указан более одного раза в конфигурации.

При указании оператора необходимо указать имя оператора, имя идентификатора или и то, и другое, в зависимости от иерархии операторов.

Вы указываете идентификаторы одним из следующих способов:

имя-идентификатора — имя-идентификатора — это ключевое слово, используемое для уникальной идентификации оператора, когда оператор может быть указан более одного раза в операторе.

значение имени-идентификатора — имя-идентификатора является ключевым словом, а значение является обязательной опциональной переменной.

имя-идентификатора [ значение1 значение2 значение3 . ] — Имя-идентификатора — это ключевое слово, которое принимает несколько значений. Скобки необходимы, когда вы указываете набор значений; однако они необязательны, если вы указываете только одно значение.

В следующих примерах показано, как операторы и идентификаторы указываются в конфигурации:

При создании файла конфигурации ASCII вы указываете операторы и идентификаторы. У каждого оператора есть предпочтительный стиль, и интерфейс командной строки использует этот стиль при отображении конфигурации в ответ на команду show режима конфигурации. Вы можете указать операторы и идентификаторы одним из следующих способов:

Утверждение, за которым следуют идентификаторы:

Утверждение, за которым следуют идентификаторы, заключенные в фигурные скобки:

Для некоторых повторяющихся идентификаторов можно использовать один набор фигурных скобок для всех операторов:

Выполнение проверки типа CLI

Когда вы указываете идентификаторы и значения, интерфейс командной строки выполняет проверку типов, чтобы убедиться, что введенные вами данные имеют правильный формат. Например, для оператора, в котором вы должны указать IP-адрес, интерфейс командной строки требует, чтобы вы вводили адрес в допустимом формате. В противном случае сообщение об ошибке указывает, что вам нужно ввести. перечисляет типы данных, которые проверяет CLI. Ниже приведены типы ввода конфигурации CLI:

Имя физического интерфейса (используется в иерархии [edit interfaces])

тип-fpc/pic/порт

Полное имя интерфейса

тип-fpc/pic/порт-канал>. логический

Полное или сокращенное название интерфейса (используется в местах, отличных от иерархии [edit interfaces])

тип- fpc pic/port>>channel>. логический >

Правильно: et, et-1, et-1/2/3:4,5

0x шестнадцатеричных байтов октет октет октет . октет >>>

Правильно: 1.2.3.4 , 0x01020304 , 128.8.1 , 128,8

1.2.3 становится 1.2.3.0 0x01020304 становится 1.2.3.4 0x010203 становится 0.1.2.3

IP-адрес (префикс назначения) и длина префикса

0x шестнадцатеричных байтов/длина > октет октет октет . октет >>> /длина >

Правильно: 10/8, 128,8/16, 1.2.3.4/32, 1.2.3.4

1.2.3 становится 1.2.3.0/32 0x01020304 становится 1.2.3.4/32 0x010203 становится 0.1.2.3/32 по умолчанию становится 0.0.0.0/0

Адрес Международной организации по стандартизации (ISO)

Правильно: 47.1234.2345.3456.00, 47123423453456.00, 47.12.34.23.45.34.56.00

47123456 становится 47.1234.56 47.12.34.56 становится 47.1234.56 4712.3456 становится 47.1234.56

Идентификатор области OSPF (ID)

0x шестнадцатеричных байтов октет октет октет . октет >>> десятичное число

Верно: 54, 0.0.0.54, 0x01020304, 1.2.3.4

54 становится 0.0.0.54

257 становится 0.0.1.1 128.8 становится 128.8.0.0 0x010203 становится 0.1.2.3

О загрузке конфигурации из файла

Следующие примеры демонстрируют процесс загрузки конфигурации из файла.

Загрузить файл конфигурации

Вы можете создать файл конфигурации в своей локальной системе, скопировать файл на устройство, а затем загрузить его в интерфейс командной строки. После того, как вы загрузили файл конфигурации, вы можете зафиксировать его, чтобы активировать конфигурацию на устройстве. Вы также можете изменить конфигурацию в интерактивном режиме с помощью интерфейса командной строки и зафиксировать ее позже.

Чтобы загрузить файл конфигурации из вашей локальной системы:

Создайте файл конфигурации с помощью текстового редактора, например Блокнота, убедившись в правильности синтаксиса файла конфигурации.
Включите в текстовый файл конфигурации один или несколько следующих параметров, чтобы выполнить необходимое действие при загрузке файла.

Объединяет текущую активную конфигурацию либо с конфигурацией в указанном вами имени файла, либо с конфигурацией, которую вы вводите в окне терминала. Операция слияния полезна, когда вы добавляете новый раздел в существующую конфигурацию. Если активная конфигурация и входящая конфигурация содержат конфликтующие операторы, операторы входящей конфигурации переопределяют операторы в активной конфигурации.

Отбрасывает текущую конфигурацию кандидата. Загружает либо конфигурацию в указанном вами имени файла, либо конфигурацию, которую вы вводите в терминале. Когда вы используете параметр переопределения и фиксируете конфигурацию, все системные процессы повторно анализируют конфигурацию. Вы можете использовать параметр переопределения на любом уровне иерархии.

Выполняет поиск тегов замены, удаляет существующие операторы с тем же именем, если они есть, и заменяет существующие операторы входящей конфигурацией. Если оператора с таким именем не существует, операция замены добавляет операторы, отмеченные тегом замены, в активную конфигурацию.

Чтобы эта операция работала, вы должны включить теги замены в текстовый файл или в конфигурацию, которую вы вводите на терминале.

Чтобы просмотреть результаты шагов настройки перед фиксацией конфигурации, введите команду show в командной строке пользователя.

Чтобы зафиксировать эти изменения в активной конфигурации, введите команду фиксации в приглашении пользователя. Вы также можете изменить конфигурацию в интерактивном режиме с помощью интерфейса командной строки и зафиксировать ее позже.

◦ Выберите параметр Integrity Visual Difference Tool, чтобы использовать инструмент Visual Difference для просмотра различий между версиями.

Если параметр Integrity Visual Difference Tool включен, а ваш администратор установил политику, запрещающую различать хранилища по элементам-ссылкам, вы не сможете использовать диспетчер жизненного цикла Integrity для различия версий хранилища по элементам-ссылкам, даже если элементы являются текстовыми файлами. Чтобы различать такие элементы с помощью стороннего инструмента, укажите параметр «Сторонний инструмент различия» или параметр «Пользовательская команда».

◦ Выберите параметр "Сторонний инструмент для определения различий", если вы хотите использовать один из следующих инструментов для просмотра различий:

В поле введите местоположение и имя исполняемого файла программы, которую вы хотите использовать, или нажмите кнопку «Обзор», чтобы перейти к исполняемому файлу.

Если включен параметр Integrity Visual Merge Tool и ваш администратор установил политику для отключения объединения хранилища по элементам-ссылкам, вы не сможете использовать диспетчер жизненного цикла Integrity для объединения ревизий для хранилища по элементам-ссылкам, даже если элементы являются текстовыми файлами. Чтобы объединить такие элементы с помощью стороннего инструмента, укажите параметр «Сторонний инструмент слияния» или параметр «Пользовательская команда».

◦ Выберите параметр "Сторонний инструмент слияния", если вы хотите использовать один из следующих инструментов для выполнения слияния вручную:

При объединении файлов, которые Visual Merge не может объединить, например, двоичных файлов или файлов MS Word, следует использовать сторонний инструмент слияния.

Вы не можете приостановить операцию слияния и пометить рабочие файлы для слияния позже при использовании стороннего инструмента слияния.

В поле введите местоположение и имя исполняемого файла для пользовательского стороннего инструмента слияния или нажмите кнопку «Обзор», чтобы перейти к исполняемому файлу.

▪ <8>путь к выходному файлу. Вы можете использовать этот аргумент, чтобы сохранить результаты слияния в файле, отличном от рабочего файла.

Сторонние инструменты слияния используются только для слияния вручную. Автоматическое слияние всегда выполняется с помощью визуального слияния.

Инструменты объединения позволяют:

Решайте конфликты в файлах моделей под контролем исходного кода, используя трехстороннее слияние. Откройте, выбрав Просмотр конфликтов.

Объедините любые два файла модели, используя двустороннее слияние. Откройте, выбрав пункты контекстного меню «Сравнить».

Объединить код функционального блока MATLAB®, используя текстовые отчеты о сравнении.

Разрешение конфликтов с помощью трехстороннего слияния моделей

Если у вас есть конфликтующий файл модели в системе управления версиями в проекте или в браузере текущей папки, щелкните правой кнопкой мыши и выберите «Просмотреть конфликты». Вы можете разрешить конфликты в инструменте слияния трехсторонней модели. Сравните свой локальный файл с конфликтующей версией и базовым файлом-предком и решите, какие изменения оставить. Вы можете разрешить конфликт и отправить свои изменения.

В проекте найдите конфликтующий файл модели, щелкните правой кнопкой мыши и выберите "Просмотреть конфликты". Вы можете увидеть View Conflicts в контекстном меню только в том случае, если ваш файл помечен системой управления версиями как конфликтующий.

Инструмент "Объединить" автоматически разрешает все возможные различия и отображает результаты на панели "Цель". Просмотрите варианты автообъединения, при необходимости отредактируйте их и решите, как разрешить оставшиеся конфликты.

Изучите столбцы отчета о слиянии.

Вверху в столбцах «Их», «Базовый» и «Мой» показаны различия в конфликтующей версии, вашей версии и базовом предке обоих файлов.

Внизу Target показывает локальный файл, в который вы объедините изменения. Инструмент "Объединить" уже автоматически объединил различия, которые он может объединить.

Изучите разницу, нажав кнопку "Далее" или щелкнув строку в столбцах "Их", "Основной" и "Мой".

Инструмент слияния отображает две модели (или, если вы выбрали параметр конфигурации, вы видите два диалоговых окна параметров конфигурации модели). По умолчанию вы видите их и целевые модели.

Выберите модели для отображения с помощью кнопок на панели инструментов на вкладке «Объединение»: «Верхняя модель» или «Нижняя модель». Просмотрите модели, чтобы решить, что объединять.

Примечание

Если вы откроете инструмент слияния с помощью View Conflicts, то модели Theys, Base и Mine будут временными файлами, показывающими конфликтующие версии. Изучите их, чтобы решить, как их объединить.Модель Target — это копия Mine, содержащая результаты ваших слияний в отчете.

Выберите версию для сохранения для каждого изменения, нажимая кнопки на панели «Цель». Вы можете объединять измененные, добавленные или удаленные узлы, а также отдельные параметры. Инструмент слияния выбирает вариант для каждого различия, которое он может разрешить автоматически. Проверьте выбор и измените его, если хотите.

Ищите предупреждения в столбце "Конфликты". Выберите кнопку, чтобы использовать «Их», «Основной» или «Мой» для каждого конфликтующего элемента.

Совет

Объединяйте блоки перед линиями и объединяйте состояния и соединения перед объединением переходов. Затем инструмент слияния попытается соединить все линии с блоками для вас. См. Советы по объединению.

Некоторые различия необходимо объединить вручную. На панели "Цель" найдите значок ручного слияния в столбце "Конфликты", который показывает, что вы должны принять меры.

Внесите изменения вручную в редакторе. Сравнительный отчет не может обновиться, чтобы показать какие-либо изменения, внесенные вами в редакторе, поэтому попробуйте внести изменения вручную после устранения всех простых слияний в отчете.

После разрешения конфликта с помощью редактора на панели «Цель» установите флажок, чтобы пометить узел как завершенный.

Изучите сводную таблицу, чтобы увидеть количество автоматических слияний и оставшихся конфликтов, которые необходимо разрешить.

Проверьте наличие изменений, отфильтрованных из текущего представления, просмотрев заголовки вкладок сводной таблицы. Заголовки вкладок «Представление с фильтром» и «Все изменения» показывают количество изменений. По умолчанию отчет скрывает все нефункциональные изменения. Отключите активные фильтры, чтобы просмотреть все выявленные изменения.

Если вас устраивают выбранные слияния и любые ручные слияния в целевом файле, нажмите «Принять и закрыть». Это действие сохраняет целевой файл со всеми вашими слияниями и помечает разрешенный конфликтующий файл в инструменте управления версиями.

Чтобы сохранить конфликт и не помечать его как разрешенный, выберите Принять и закрыть > Сохранить и закрыть.

Чтобы узнать больше об устранении конфликтов в списке изменений измененных файлов в проекте, см. раздел Разрешение конфликтов.

Используйте трехстороннее слияние с внешними инструментами управления версиями

Если вы используете систему управления версиями вне MATLAB, вы можете настроить внешние инструменты управления версиями, чтобы открыть трехстороннее слияние (или двустороннее слияние для различий).

Открыть трехстороннее слияние без использования системы управления версиями

Если вы не используете систему управления версиями или хотите выбрать три файла для слияния, вы можете открыть Three-Way Merge с помощью функции slxmlcomp.slMerge . Укажите файлы для объединения, например:

Откроется трехстороннее слияние, где вы можете объединить изменения в baseFile , mineFile и itssFile в targetFile .

Двустороннее слияние моделей

Вы можете объединить две модели Simulink ® из сравнительного отчета. Элементы контекстного меню «Сравнить» из проекта или обозревателя текущей папки открывают двустороннее слияние моделей. Если вы используете систему управления версиями и хотите разрешать конфликты с помощью трехстороннего слияния моделей, см. раздел Разрешение конфликтов с помощью трехстороннего слияния моделей.

Функция слияния позволяет объединить две версии проекта, смоделированного в Simulink. Вы можете объединять отдельные параметры, блоки или целые подсистемы. Целые подсистемы могут быть объединены целиком только в том случае, если они полностью вставлены или удалены подсистемы.

На вкладке "Сравнение" нажмите "Режим слияния". Панель «Цель» отображается в нижней части отчета.

Используйте тот же рабочий процесс, что и при трехстороннем слиянии. С помощью кнопок выберите различия, которые нужно сохранить в целевом файле.

Совет

Объединяйте блоки перед линиями и объединяйте состояния и соединения перед объединением переходов. См. Советы по объединению.

Просмотрите результаты в отчете и моделях. Щелкните Сохранить файл. Сохранить файл копирует временный целевой файл поверх правого файла в сравнении и повторно запускает сравнение.

(Необязательно) Чтобы отменить все операции слияния, нажмите «Закрыть слияние», не сохраняя файл.

Проверьте изменения слияния в редакторе Simulink. При необходимости подключите любые линии, которые программа не подключила автоматически. Сравнительный отчет не обновляется, чтобы показать какие-либо изменения, внесенные вами в редакторе.

Советы по объединению

В части отчета Simulink объедините модели в следующем порядке. В целевом файле:

Удалите строки, которые вы не хотите сохранять.

Удалите блоки, которые вы не хотите сохранять.

Добавьте блоки, которые хотите сохранить.

Добавьте строки, которые хотите сохранить.

Выберите параметры, которые хотите сохранить.

Вы должны объединить состояния и соединения перед объединением переходов, иначе отчет не сможет установить соединения.

Пример, показывающий, как объединить изменения, затрагивающие несколько узлов, см. в разделе Сравнение и объединение моделей Simulink, содержащих поток состояний.

Не все параметры можно объединить. В этом случае на целевой панели отображается только один переключатель, указывающий версию целевой модели.

Информацию об объединении моделей с одинаковыми именами см. в разделе Сравнение моделей с одинаковыми именами.

Объединить код функционального блока MATLAB

Чтобы объединить различия в коде блока MATLAB Function, создайте отчет о сравнении для родительских моделей.

Нажмите кнопку "Режим слияния".

При этом создается и открывается третий файл с именем targetFile. Он может содержать изменения левой или правой модели.

Используйте кнопки справа от отчета, чтобы выбрать нужные изменения в целевом файле.

Сохраните эти изменения в нужной модели с помощью кнопки "Сохранить файл" на панели инструментов.

На этой странице описывается этап $merge, который выводит результаты конвейера агрегации в коллекцию. Информацию об операторе $mergeObjects, который объединяет документы в один документ, см. в разделе $mergeObjects .

Новое в версии 4.2.

Записывает результаты конвейера агрегации в указанную коллекцию. Оператор $merge должен быть последним этапом конвейера.

Может выводить в коллекцию в той же или другой базе данных.

Начиная с MongoDB 4.4:

может выводить в ту же коллекцию, которая агрегируется. Дополнительные сведения см. в разделе Вывод в ту же коллекцию, которая подвергается агрегированию.

Конвейеры со стадией $merge могут работать на вторичных узлах набора реплик, если на всех узлах в кластере для featureCompatibilityVersion установлено значение 4.4 или выше, а параметр Read Preference разрешает вторичное чтение.

Операции чтения оператора $merge отправляются на вторичные узлы, а операции записи выполняются только на основном узле.
Не все версии драйверов поддерживают нацеливание операций $merge на вторичные узлы набора реплик. Проверьте документацию по драйверу, чтобы узнать, когда в вашем драйвере была добавлена поддержка операций чтения $merge, выполняемых на вторичных узлах.

Сравнение с этапом $out, который также выводит результаты агрегирования в коллекцию, см. в разделе Сравнение $merge и $out.

$merge может включать результаты конвейера в существующую выходную коллекцию, а не выполнять полную замену коллекции. Эта функция позволяет пользователям создавать материализованные представления по запросу, в которых содержимое выходной коллекции постепенно обновляется при запуске конвейера.

Дополнительную информацию об этом варианте использования см. в материализованных представлениях по запросу, а также в примерах на этой странице.

Материализированные представления отделены от представлений только для чтения. Информацию о создании представлений только для чтения см. в разделе Представления только для чтения.

Синтаксис

$merge имеет следующий синтаксис:

Если вы используете все параметры по умолчанию для $merge , включая запись в коллекцию в той же базе данных, вы можете использовать упрощенную форму:

$merge принимает документ со следующими полями:

Выходная коллекция. Укажите:

Имя коллекции в виде строки для вывода в коллекцию в той же базе данных, где выполняется агрегирование. Например:

Имя базы данных и коллекции в документе для вывода в коллекцию в указанной базе данных. Например:

Если выходная коллекция не существует, $merge создает коллекцию:

Для набора реплик или отдельной базы данных, если выходная база данных не существует, $merge также создает базу данных.
Для сегментированного кластера указанная выходная база данных уже должна существовать.

Необязательно. Поле или поля, выступающие в качестве уникального идентификатора документа. Идентификатор определяет, соответствует ли результирующий документ существующему документу в выходной коллекции. Укажите:

Имя одного поля в виде строки. Например:

Комбинация полей в массиве. Например:

Порядок полей в массиве не имеет значения, и вы не можете указать одно и то же поле несколько раз.

Для указанного поля или полей:

Документы результатов агрегирования должны содержать поля, указанные в поле on , если только поле on не является полем _id. Если поле _id отсутствует в документе результатов, MongoDB добавит его автоматически.
Указанное поле или поля не могут содержать пустое значение или значение массива.

Для $merge требуется уникальный индекс с ключами, соответствующими полям идентификатора on. Хотя порядок спецификации ключа индекса не имеет значения, уникальный индекс должен содержать только поля on в качестве ключей.

Индекс также должен иметь те же параметры сортировки, что и параметры агрегации.
Уникальный индекс может быть разреженным индексом.
Уникальный индекс не может быть частичным индексом.
Для уже существующих коллекций выходных данных должен существовать соответствующий индекс.

Значение по умолчанию on зависит от выходной коллекции:

Если выходная коллекция не существует, идентификатор on должен быть и по умолчанию равен полю _id. Соответствующий уникальный индекс _id создается автоматически.

Чтобы использовать другое поле (поля) идентификатора для несуществующей коллекции, вы можете сначала создать коллекцию, создав уникальный индекс для нужных полей. См. пример в разделе о несуществующей коллекции выходных данных.

Необязательно. Поведение $merge, если результирующий документ и существующий документ в коллекции имеют одинаковое значение для указанных полей on.

Вы можете указать:

Одна из предопределенных строк действий:

Замените существующий документ в выходной коллекции соответствующим документом результатов.

При выполнении замены замещающий документ не может привести к изменению значения _id или, если выходная коллекция сегментирована, значения ключа сегмента. В противном случае операция выдаст ошибку.

Чтобы избежать этой ошибки, если поле on не включает поле _id, удалите поле _id в результатах агрегирования, чтобы избежать ошибки, например, с предшествующим этапом $unset и т. д.

Сохранить существующий документ в выходной коллекции.

Объедините совпадающие документы (аналогично оператору $mergeObjects).

Если документ результатов содержит поля, которых нет в существующем документе, добавьте эти новые поля в существующий документ.
Если документ результатов содержит поля в существующем документе, замените существующие значения полей значениями из документа результатов.

Например, если в выходной коллекции есть документ:

И результаты агрегации имеют документ:

Затем объединенный документ:

При выполнении слияния объединенный документ не может привести к изменению значения _id или, если выходная коллекция сегментирована, значения ключа сегмента. В противном случае операция выдаст ошибку.

Остановить и завершить операцию агрегирования. Любые изменения в выходной коллекции из предыдущих документов не отменяются.

Конвейер агрегации для обновления документа в коллекции.

Конвейер может состоять только из следующих этапов:

Конвейер не может изменить значение поля on. Например, если вы выполняете сопоставление в поле месяц , конвейер не может изменить поле месяца.

Конвейер whenMatched может напрямую обращаться к полям существующих документов в выходной коллекции с помощью $ .

Чтобы получить доступ к полям из документов результатов агрегирования, используйте:

Встроенная переменная $$new для доступа к полю. В частности, $$new. . Переменная $$new доступна, только если опущена спецификация let.

Начиная с MongoDB 4.2.2 переменная $$new зарезервирована и не может быть переопределена.

Определяемые пользователем переменные в поле let.

Укажите префикс с двойным знаком доллара ($$) вместе с именем переменной в форме $$ . Например, $$год. Если для переменной задан документ, вы также можете включить поле документа в форме $$. . Например, $$год.месяц .

Необязательно. Указывает переменные для использования в конвейере whenMatched.

Укажите документ с именами переменных и выражениями значений:

Если не указано, по умолчанию используется < new: "$$ROOT" > (см. ROOT ). Конвейер whenMatched может получить доступ к переменной $$new.

Начиная с MongoDB 4.2.2 переменная $$new зарезервирована и не может быть переопределена.

Чтобы получить доступ к переменным в конвейере whenMatched:

Необязательно. Поведение $merge, если результирующий документ не соответствует существующему документу в выходной коллекции.

Вы можете указать одну из предопределенных строк действия:

Вставьте документ в выходную коллекцию.

Удалить документ. В частности, $merge не вставляет документ в выходную коллекцию.

Остановить и завершить операцию агрегирования. Любые изменения, уже записанные в выходную коллекцию, не отменяются.

Соображения

Генерация поля _id

Если поле _id отсутствует в документе из результатов конвейера агрегации, этап $merge создает его автоматически.

Например, в следующем конвейере агрегации $project исключает поле _id из документов, переданных в $merge .Когда $merge записывает эти документы в "newCollection", $merge создает новое поле _id и значение.

Создать новую коллекцию, если выходная коллекция не существует

Операция $merge создает новую коллекцию, если указанная выходная коллекция не существует.

Выходная коллекция создается, когда $merge записывает в коллекцию первый документ, и сразу становится видимой.
Если агрегация завершается с ошибкой, любые записи, выполненные с помощью $merge до возникновения ошибки, не будут откатываться.

Для набора реплик или отдельной базы данных, если выходная база данных не существует, $merge также создает базу данных.

Для сегментированного кластера указанная выходная база данных уже должна существовать.

Если выходная коллекция не существует, $merge требует, чтобы идентификатор on был полем _id. Чтобы использовать другое значение поля для несуществующей коллекции, вы можете сначала создать коллекцию, сначала создав уникальный индекс для нужных полей. Например, если выходная коллекция newDailySales201905 не существует и вы хотите указать поле salesDate в качестве идентификатора on:

Вывод в общую коллекцию

Этап $merge может выводить в сегментированную коллекцию. Когда выходная коллекция сегментирована, $merge использует поле _id и все поля ключа сегмента в качестве идентификатора по умолчанию. Если вы переопределяете значение по умолчанию, идентификатор on должен включать все поля ключа сегмента:

Например, в базе данных с включенным сегментированием используйте метод sh.shardCollection() для создания новой сегментированной коллекции newrestaurants с полем почтового индекса в качестве ключа сегмента.

Коллекция newrestaurants будет содержать документы с информацией об открытии новых ресторанов по месяцам (поле даты) и почтовому индексу (ключ сегмента); в частности, идентификатор on — ["дата", "почтовый индекс"] (порядок полей не имеет значения). Поскольку для $merge требуется уникальный индекс с ключами, соответствующими полям идентификатора, создайте уникальный индекс (порядок полей не имеет значения): [ 1 ]

С созданными сегментированными коллекциями ресторанов и уникальным индексом вы можете использовать $merge для вывода результатов агрегирования в эту коллекцию, сопоставляя их по [ "date", "postcode" ] , как в этом примере:

[1]

Метод sh.shardCollection() также может создавать уникальный индекс в ключе сегмента при передаче параметра , если: ключ сегмента основан на диапазоне, коллекция пуста и уникальный индекс в ключе сегмента еще не существует. В предыдущем примере, поскольку идентификатор on является ключом сегмента и другим полем, требуется отдельная операция для создания соответствующего индекса.

Заменить документы ($merge) или заменить коллекцию ($out)

$merge может заменить существующий документ в выходной коллекции, если результаты агрегирования содержат документ или документы, соответствующие спецификации on. Таким образом, $merge может заменить все документы в существующей коллекции, если результаты агрегирования включают совпадающие документы для всех существующих документов в коллекции, и вы укажете «заменить» для whenMatched.

Однако, чтобы заменить существующую коллекцию независимо от результатов агрегирования, используйте вместо этого $out.

Существующие документы и значения _id и ключа сегмента

Ошибки $merge, если $merge приводит к изменению значения _id существующего документа.

Кроме того, для сегментированной коллекции $merge также генерирует ошибку, если приводит к изменению значения ключа сегмента существующего документа.

Любая запись, выполненная с помощью $merge до возникновения ошибки, не будет отменена.

Ограничения уникального индекса

Если уникальный индекс, используемый $merge для полей on, удаляется в середине агрегации, нет гарантии, что агрегация будет уничтожена. Если объединение продолжается, нет гарантии, что в документах не будет дубликатов значений полей.

Если $merge попытается записать документ, который нарушает какой-либо уникальный индекс в выходной коллекции, операция выдает ошибку. Например:

который нарушает уникальный индекс, отличный от индекса в поле(ях) on. если в коллекции есть соответствующий документ. В частности, операция пытается вставить соответствующий документ, который нарушает уникальный индекс в полях on. с новым документом, который нарушает уникальный индекс, отличный от индекса в поле(ях) on. это приводит к тому, что документ нарушает уникальный индекс, отличный от индекса в поле(ях) on.

Поведение конвейера whenMatched

Начиная с MongoDB 4.2.2, если для стадии $merge выполняются все следующие условия:

Значение whenMatched — конвейер агрегации.
Значение whenNotMatched равно вставке и
Нет совпадений для документа в выходной коллекции,

$merge вставляет документ непосредственно в выходную коллекцию.

До MongoDB 4.2.2, когда выполняются эти условия для этапа $merge, конвейер, указанный в поле whenMatched, выполняется с пустым входным документом. Результирующий документ из конвейера вставляется в выходную коллекцию.

Читайте также: