.. Document meta

:orphan:

.. |antsibull-internal-nbsp| unicode:: 0xA0
    :trim:

.. meta::
  :antsibull-docs: 2.16.3

.. Anchors

.. _ansible_collections.middleware_automation.amq.lists_mergeby_filter:

.. Anchors: short name for ansible.builtin

.. Title

lists_mergeby -- Merge two or more lists of dictionaries by a given attribute
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. Collection note

.. note::
    This filter plugin is part of the `middleware_automation.amq collection <https://galaxy.ansible.com/ui/repo/published/middleware_automation/amq/>`_.

    It is not included in ``ansible-core``.
    To check whether it is installed, run :code:`ansible-galaxy collection list`.

    To install it, use: :code:`ansible-galaxy collection install middleware\_automation.amq`.

    To use it in a playbook, specify: :code:`middleware_automation.amq.lists_mergeby`.

.. version_added

.. rst-class:: ansible-version-added

New in middleware\_automation.amq 2.0.0

.. contents::
   :local:
   :depth: 1

.. Deprecated


Synopsis
--------

.. Description

- Merge two or more lists by attribute :ansopt:`middleware\_automation.amq.lists\_mergeby#filter:index`. Optional parameters :ansopt:`middleware\_automation.amq.lists\_mergeby#filter:recursive` and :ansopt:`middleware\_automation.amq.lists\_mergeby#filter:list\_merge` control the merging of the lists in values. The function merge\_hash from ansible.utils.vars is used. To learn details on how to use the parameters :ansopt:`middleware\_automation.amq.lists\_mergeby#filter:recursive` and :ansopt:`middleware\_automation.amq.lists\_mergeby#filter:list\_merge` see Ansible User's Guide chapter "Using filters to manipulate data" section "Combining hashes/dictionaries".


.. Aliases


.. Requirements





.. Input

Input
-----

This describes the input of the filter, the value before ``| middleware_automation.amq.lists_mergeby``.

.. raw:: html

  <table class="colwidths-auto ansible-option-table docutils align-default" style="width: 100%">
  <thead>
  <tr class="row-odd">
    <th class="head"><p>Parameter</p></th>
    <th class="head"><p>Comments</p></th>
  </tr>
  </thead>
  <tbody>
  <tr class="row-even">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-_input"></div>
      <p class="ansible-option-title"><strong>Input</strong></p>
      <a class="ansibleOptionLink" href="#parameter-_input" title="Permalink to this option"></a>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">list</span>
        / <span class="ansible-option-elements">elements=dictionary</span>
        / <span class="ansible-option-required">required</span>
      </p>

    </div></td>
    <td><div class="ansible-option-cell">
      <p>A list of dictionaries.</p>
    </div></td>
  </tr>
  </tbody>
  </table>





.. Positional

Positional parameters
---------------------

This describes positional parameters of the filter. These are the values ``positional1``, ``positional2`` and so on in the following
example: ``input | middleware_automation.amq.lists_mergeby(positional1, positional2, ...)``

.. raw:: html

  <table class="colwidths-auto ansible-option-table docutils align-default" style="width: 100%">
  <thead>
  <tr class="row-odd">
    <th class="head"><p>Parameter</p></th>
    <th class="head"><p>Comments</p></th>
  </tr>
  </thead>
  <tbody>
  <tr class="row-even">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-another_list"></div>
      <p class="ansible-option-title"><strong>another_list</strong></p>
      <a class="ansibleOptionLink" href="#parameter-another_list" title="Permalink to this option"></a>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">list</span>
        / <span class="ansible-option-elements">elements=dictionary</span>
      </p>

    </div></td>
    <td><div class="ansible-option-cell">
      <p>Another list of dictionaries. This parameter can be specified multiple times.</p>
    </div></td>
  </tr>
  <tr class="row-odd">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-index"></div>
      <p class="ansible-option-title"><strong>index</strong></p>
      <a class="ansibleOptionLink" href="#parameter-index" title="Permalink to this option"></a>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">string</span>
        / <span class="ansible-option-required">required</span>
      </p>

    </div></td>
    <td><div class="ansible-option-cell">
      <p>The dictionary key that must be present in every dictionary in every list that is used to merge the lists.</p>
    </div></td>
  </tr>
  </tbody>
  </table>




.. Options

Keyword parameters
------------------

This describes keyword parameters of the filter. These are the values ``key1=value1``, ``key2=value2`` and so on in the following
example: ``input | middleware_automation.amq.lists_mergeby(key1=value1, key2=value2, ...)``

.. raw:: html

  <table class="colwidths-auto ansible-option-table docutils align-default" style="width: 100%">
  <thead>
  <tr class="row-odd">
    <th class="head"><p>Parameter</p></th>
    <th class="head"><p>Comments</p></th>
  </tr>
  </thead>
  <tbody>
  <tr class="row-even">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-list_merge"></div>
      <p class="ansible-option-title"><strong>list_merge</strong></p>
      <a class="ansibleOptionLink" href="#parameter-list_merge" title="Permalink to this option"></a>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">string</span>
      </p>

    </div></td>
    <td><div class="ansible-option-cell">
      <p>Modifies the behaviour when the dictionaries (hashes) to merge contain arrays/lists.</p>
      <p class="ansible-option-line"><strong class="ansible-option-choices">Choices:</strong></p>
      <ul class="simple">
        <li><p><code class="ansible-value literal notranslate ansible-option-default-bold"><strong>&#34;replace&#34;</strong></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
        <li><p><code class="ansible-value literal notranslate ansible-option-choices-entry">&#34;keep&#34;</code></p></li>
        <li><p><code class="ansible-value literal notranslate ansible-option-choices-entry">&#34;append&#34;</code></p></li>
        <li><p><code class="ansible-value literal notranslate ansible-option-choices-entry">&#34;prepend&#34;</code></p></li>
        <li><p><code class="ansible-value literal notranslate ansible-option-choices-entry">&#34;append_rp&#34;</code></p></li>
        <li><p><code class="ansible-value literal notranslate ansible-option-choices-entry">&#34;prepend_rp&#34;</code></p></li>
      </ul>

    </div></td>
  </tr>
  <tr class="row-odd">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="parameter-recursive"></div>
      <p class="ansible-option-title"><strong>recursive</strong></p>
      <a class="ansibleOptionLink" href="#parameter-recursive" title="Permalink to this option"></a>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">boolean</span>
      </p>

    </div></td>
    <td><div class="ansible-option-cell">
      <p>Should the combine recursively merge nested dictionaries (hashes).</p>
      <p><b>Note:</b> It does not depend on the value of the <code class='docutils literal notranslate'>hash_behaviour</code> setting in <code class='docutils literal notranslate'>ansible.cfg</code>.</p>
      <p class="ansible-option-line"><strong class="ansible-option-choices">Choices:</strong></p>
      <ul class="simple">
        <li><p><code class="ansible-value literal notranslate ansible-option-default-bold"><strong>false</strong></code> <span class="ansible-option-choices-default-mark">← (default)</span></p></li>
        <li><p><code class="ansible-value literal notranslate ansible-option-choices-entry">true</code></p></li>
      </ul>

    </div></td>
  </tr>
  </tbody>
  </table>



.. Attributes


.. Notes

Notes
-----

.. note::
   - When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters:
     ``input | middleware_automation.amq.lists_mergeby(positional1, positional2, key1=value1, key2=value2)``

.. Seealso


.. Examples

Examples
--------

.. code-block:: yaml+jinja

    - name: Merge two lists
      ansible.builtin.debug:
        msg: >-
          {{ list1 | middleware_automation.amq.lists_mergeby(
                        list2,
                        'index',
                        recursive=True,
                        list_merge='append'
                     ) }}"
      vars:
        list1:
          - index: a
            value: 123
          - index: b
            value: 42
        list2:
          - index: a
            foo: bar
          - index: c
            foo: baz
      # Produces the following list of dictionaries:
      #   {
      #     "index": "a",
      #     "foo": "bar",
      #     "value": 123
      #   },
      #   {
      #     "index": "b",
      #     "value": 42
      #   },
      #   {
      #     "index": "c",
      #     "foo": "baz"
      #   }



.. Facts


.. Return values

Return Value
------------

.. raw:: html

  <table class="colwidths-auto ansible-option-table docutils align-default" style="width: 100%">
  <thead>
  <tr class="row-odd">
    <th class="head"><p>Key</p></th>
    <th class="head"><p>Description</p></th>
  </tr>
  </thead>
  <tbody>
  <tr class="row-even">
    <td><div class="ansible-option-cell">
      <div class="ansibleOptionAnchor" id="return-_value"></div>
      <p class="ansible-option-title"><strong>Return value</strong></p>
      <a class="ansibleOptionLink" href="#return-_value" title="Permalink to this return value"></a>
      <p class="ansible-option-type-line">
        <span class="ansible-option-type">list</span>
        / <span class="ansible-option-elements">elements=dictionary</span>
      </p>
    </div></td>
    <td><div class="ansible-option-cell">
      <p>The merged list.</p>
      <p class="ansible-option-line"><strong class="ansible-option-returned-bold">Returned:</strong> success</p>
    </div></td>
  </tr>
  </tbody>
  </table>



..  Status (Presently only deprecated)


.. Authors

Authors
~~~~~~~

- Vladimir Botka (@vbotka)


.. hint::
    Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.

.. Extra links


.. Parsing errors