# xarray.merge

`xarray.``merge`(objects: Iterable[Union[DataArray, CoercibleMapping]], compat: str = 'no_conflicts', join: str = 'outer', fill_value: object = <NA>) → Dataset

  Merge any number of xarray objects into a single Dataset as variables.

  Parameters:

  - objects (Iterable[Union[xarray.Dataset, xarray.DataArray, dict]]) – Merge together all variables from these objects. If any of them are DataArray objects, they must have a name.
  - compat ({'identical', 'equals', 'broadcast_equals', 'no_conflicts', 'override'}, optional) –

    String indicating how to compare variables of the same name for potential conflicts:

    - ’broadcast_equals’: all values must be equal when variables are broadcast against each other to ensure common dimensions.
    - ’equals’: all values and dimensions must be the same.
    - ’identical’: all values, dimensions and attributes must be the same.
    - ’no_conflicts’: only values which are not null in both datasets must be equal. The returned dataset then contains the combination of all non-null values.
    - ’override’: skip comparing and pick variable from first dataset
  - join ({'outer', 'inner', 'left', 'right', 'exact'}, optional) –

    String indicating how to combine differing indexes in objects.

    - ’outer’: use the union of object indexes
    - ’inner’: use the intersection of object indexes
    - ’left’: use indexes from the first object with each dimension
    - ’right’: use indexes from the last object with each dimension
    - ’exact’: instead of aligning, raise ValueError when indexes to be aligned are not equal
    - ’override’: if indexes are of same size, rewrite indexes to be those of the first object with that dimension. Indexes for the same dimension must have the same size in all objects.
  - fill_value (scalar, optional) – Value to use for newly missing values

  Returns: | Dataset with combined variables from each object.
  Return type: | Dataset

  Examples

      >>> import xarray as xr
      >>> x = xr.DataArray(
      ...     [[1.0, 2.0], [3.0, 5.0]],
      ...     dims=("lat", "lon"),
      ...     coords={"lat": [35.0, 40.0], "lon": [100.0, 120.0]},
      ...     name="var1",
      ... )
      >>> y = xr.DataArray(
      ...     [[5.0, 6.0], [7.0, 8.0]],
      ...     dims=("lat", "lon"),
      ...     coords={"lat": [35.0, 42.0], "lon": [100.0, 150.0]},
      ...     name="var2",
      ... )
      >>> z = xr.DataArray(
      ...     [[0.0, 3.0], [4.0, 9.0]],
      ...     dims=("time", "lon"),
      ...     coords={"time": [30.0, 60.0], "lon": [100.0, 150.0]},
      ...     name="var3",
      ... )

      >>> x
      <xarray.DataArray 'var1' (lat: 2, lon: 2)>
      array([[1., 2.],
             [3., 5.]])
      Coordinates:
      * lat      (lat) float64 35.0 40.0
      * lon      (lon) float64 100.0 120.0

      >>> y
      <xarray.DataArray 'var2' (lat: 2, lon: 2)>
      array([[5., 6.],
             [7., 8.]])
      Coordinates:
      * lat      (lat) float64 35.0 42.0
      * lon      (lon) float64 100.0 150.0

      >>> z
      <xarray.DataArray 'var3' (time: 2, lon: 2)>
      array([[0., 3.],
             [4., 9.]])
      Coordinates:
      * time     (time) float64 30.0 60.0
      * lon      (lon) float64 100.0 150.0

      >>> xr.merge([x, y, z])
      <xarray.Dataset>
      Dimensions:  (lat: 3, lon: 3, time: 2)
      Coordinates:
      * lat      (lat) float64 35.0 40.0 42.0
      * lon      (lon) float64 100.0 120.0 150.0
      * time     (time) float64 30.0 60.0
      Data variables:
          var1     (lat, lon) float64 1.0 2.0 nan 3.0 5.0 nan nan nan nan
          var2     (lat, lon) float64 5.0 nan 6.0 nan nan nan 7.0 nan 8.0
          var3     (time, lon) float64 0.0 nan 3.0 4.0 nan 9.0

      >>> xr.merge([x, y, z], compat='identical')
      <xarray.Dataset>
      Dimensions:  (lat: 3, lon: 3, time: 2)
      Coordinates:
      * lat      (lat) float64 35.0 40.0 42.0
      * lon      (lon) float64 100.0 120.0 150.0
      * time     (time) float64 30.0 60.0
      Data variables:
          var1     (lat, lon) float64 1.0 2.0 nan 3.0 5.0 nan nan nan nan
          var2     (lat, lon) float64 5.0 nan 6.0 nan nan nan 7.0 nan 8.0
          var3     (time, lon) float64 0.0 nan 3.0 4.0 nan 9.0

      >>> xr.merge([x, y, z], compat='equals')
      <xarray.Dataset>
      Dimensions:  (lat: 3, lon: 3, time: 2)
      Coordinates:
      * lat      (lat) float64 35.0 40.0 42.0
      * lon      (lon) float64 100.0 120.0 150.0
      * time     (time) float64 30.0 60.0
      Data variables:
          var1     (lat, lon) float64 1.0 2.0 nan 3.0 5.0 nan nan nan nan
          var2     (lat, lon) float64 5.0 nan 6.0 nan nan nan 7.0 nan 8.0
          var3     (time, lon) float64 0.0 nan 3.0 4.0 nan 9.0

      >>> xr.merge([x, y, z], compat='equals', fill_value=-999.)
      <xarray.Dataset>
      Dimensions:  (lat: 3, lon: 3, time: 2)
      Coordinates:
      * lat      (lat) float64 35.0 40.0 42.0
      * lon      (lon) float64 100.0 120.0 150.0
      * time     (time) float64 30.0 60.0
      Data variables:
          var1     (lat, lon) float64 1.0 2.0 -999.0 3.0 ... -999.0 -999.0 -999.0
          var2     (lat, lon) float64 5.0 -999.0 6.0 -999.0 ... -999.0 7.0 -999.0 8.0
          var3     (time, lon) float64 0.0 -999.0 3.0 4.0 -999.0 9.0

      >>> xr.merge([x, y, z], join='override')
      <xarray.Dataset>
      Dimensions:  (lat: 2, lon: 2, time: 2)
      Coordinates:
      * lat      (lat) float64 35.0 40.0
      * lon      (lon) float64 100.0 120.0
      * time     (time) float64 30.0 60.0
      Data variables:
          var1     (lat, lon) float64 1.0 2.0 3.0 5.0
          var2     (lat, lon) float64 5.0 6.0 7.0 8.0
          var3     (time, lon) float64 0.0 3.0 4.0 9.0

      >>> xr.merge([x, y, z], join='inner')
      <xarray.Dataset>
      Dimensions:  (lat: 1, lon: 1, time: 2)
      Coordinates:
      * lat      (lat) float64 35.0
      * lon      (lon) float64 100.0
      * time     (time) float64 30.0 60.0
      Data variables:
          var1     (lat, lon) float64 1.0
          var2     (lat, lon) float64 5.0
          var3     (time, lon) float64 0.0 4.0

      >>> xr.merge([x, y, z], compat='identical', join='inner')
      <xarray.Dataset>
      Dimensions:  (lat: 1, lon: 1, time: 2)
      Coordinates:
      * lat      (lat) float64 35.0
      * lon      (lon) float64 100.0
      * time     (time) float64 30.0 60.0
      Data variables:
          var1     (lat, lon) float64 1.0
          var2     (lat, lon) float64 5.0
          var3     (time, lon) float64 0.0 4.0

      >>> xr.merge([x, y, z], compat='broadcast_equals', join='outer')
      <xarray.Dataset>
      Dimensions:  (lat: 3, lon: 3, time: 2)
      Coordinates:
      * lat      (lat) float64 35.0 40.0 42.0
      * lon      (lon) float64 100.0 120.0 150.0
      * time     (time) float64 30.0 60.0
      Data variables:
          var1     (lat, lon) float64 1.0 2.0 nan 3.0 5.0 nan nan nan nan
          var2     (lat, lon) float64 5.0 nan 6.0 nan nan nan 7.0 nan 8.0
          var3     (time, lon) float64 0.0 nan 3.0 4.0 nan 9.0

      >>> xr.merge([x, y, z], join='exact')
      Traceback (most recent call last):
      ...
      ValueError: indexes along dimension 'lat' are not equal

  Raises: | `xarray.MergeError` – If any variables with the same name have conflicting values.

  See also

  `concat()`