xts (version 0.12.1)

merge.xts: Merge xts Objects


Used to perform merge operation on xts objects by time (index). Given the inherent ordered nature of xts time-series, a merge-join style merge allows for optimally efficient joins.


# S3 method for xts
      all = TRUE,
      fill = NA,
      suffixes = NULL,
      join = "outer",
      retside = TRUE,
      retclass = "xts",
      tzone = NULL,


A new xts object containing the appropriate elements of the objects passed in to be merged.



one or more xts objects, or objects coercible to class xts


a logical vector indicating merge type


values to be used for missing elements


to be added to merged column names


type of database join


which side of the merged object should be returned (2-case only)


object to return


time zone of merged object


not currently used


not currently used


Jeffrey A. Ryan


This is an xts method compatible with merge.zoo, as xts extends zoo. That documentation should also be referenced. Difference are noted where applicable.

Implemented almost entirely in custom C-level code, it is possible using either the all argument or the join argument to implement all common database join operations along the to-be-merged objects time-index: ‘outer’ (full outer - all rows), ‘inner’ (only rows with common indexes), ‘left’ (all rows in the left object, and those that match in the right), and ‘right’ (all rows in the right object, and those that match in the left).

The above join types can also be expressed as a vector of logical values passed to all. c(TRUE,TRUE) or TRUE for ‘join="outer"’, c(FALSE,FALSE) or FALSE for ‘join="inner"’, c(TRUE, FALSE) for ‘join="left"’, and c(FALSE,TRUE) for ‘join="right"’.

Note that the all and join arguments imply a two case scenario. For merging more than two objects, they will simply fall back to a full outer or full inner join, depending on the first position of all, as left and right can be ambiguous with respect to sides.

To do something along the lines of merge.zoo's method of joining based on an all argument of the same length of the arguments to join, see the example.

The resultant object will have the timezone of the leftmost argument if available. Use tzone to override.

If retclass is NULL, the joined objects will be split and reassigned silently back to the original environment they are called from. This is for backward compatibility with zoo, though unused by xts.

If retclass is FALSE the object will be stripped of its class attribute. This is for internal use.


Merge Join Discussion: https://blogs.msdn.microsoft.com/craigfr/2006/08/03/merge-join/


Run this code
(x <- xts(4:10, Sys.Date()+4:10))
(y <- xts(1:6, Sys.Date()+1:6))

merge(x,y, join='inner')
merge(x,y, join='left')
merge(x,y, join='right')

merge.zoo(zoo(x),zoo(y),zoo(x), all=c(TRUE, FALSE, TRUE))

# zero-width objects (only index values) can be used
xi <- xts( , index(x))
merge(y, xi)

Run the code above in your browser using DataCamp Workspace