Merge

Merge( object1, object2, [customResolver] )
Merge( object1, object2, [customResolver] )
Merge( object1, object2, [customResolver] )
Merge( object1, object2, [customResolver] )
merge( object1, object2, [customResolver] )
Merge( object1, object2, [customResolver] )

Description

The Merge function combines two or more objects into one, by merging the fields and values from both objects into a new object.

The merge starts with a copy of object1 — called result — and then merges object2 into result. If object2 is an array of objects to merge, each object within object2 is merged into result in turn.

During the merge, each field of the object to be merged into result is processed by a resolver function, which determines which value to use in result when there is a common field. The default resolver always decides to use the value from the object to be merged, overriding the value in result.

You can provide an optional customResolver function that overrides the default resolver, and is used to determine which value to use.

When the resolver returns a null value, Merge deletes that field in result.

Parameters

Argument Type Definition and Requirements

object1

The first object to merge with the second object.

object2

Object or Array of Objects.

The second object, or array of objects, to merge with the first object. If an array of objects is provided, each object in the array is merged with object1 in turn.

customResolver

Optional - A lambda function that replaces the default resolver and decides which value to use during the merge.

The customResolver function has the signature:

(field, value1, value2) ⇒ newValue

where field is the name of the field that exists in both object1 and object2, and value1 and value2 are the respective values for that field.

If customResolver returns a null, Merge deletes field from the result.

Returns

An object that is the result of merging object1 with object2 (and any additional objects that you may have provided).

Examples

  1. The following query demonstrates a merge of two objects where there is no key conflict:

    Value result = await client.Query(
      Merge(
        Obj("a", "Apple", "b", "Banana"),
        Obj("x", "width", "y", "height")
      )
    );
    result, err := client.Query(
      f.Merge(
          f.Obj{ "a": "Apple", "b": "Banana", },
          f.Obj{ "x": "width", "y": "height", }))
    System.out.println(
      client.query(
        Merge(
          Obj("a", "Apple", "b", "Banana"),
          Obj("x", "width", "y", "height")
        )
      ).get());
    client.query(
      q.Merge(
        { a: 'Apple', b: 'Banana' },
        { x: 'width', y: 'height' },
      )
    )
    .then((ret) => console.log(ret))
    result = client.query(
      q.merge(
        { "a": "Apple", "b": "Banana" },
        { "x": "width", "y": "height" }
      )
    )
    print(result)
    client.query(
      Merge(
        Obj("a" -> "Apple", "b" -> "Banana"),
        Obj("x" -> "width", "y" -> "height")
     )
    )
    {
      "object": {
        "a": "Apple",
        "b": "Banana",
        "x": "width",
        "y": "height"
      }
    }
    map[a:Apple b:Banana x:width y:height]
    {a: "Apple", b: "Banana", x: "width", y: "height"}
    { a: 'Apple', b: 'Banana', x: 'width', y: 'height' }
    {'a': 'Apple', 'b': 'Banana', 'x': 'width', 'y': 'height'}
    {a: "Apple", b: "Banana", x: "width", y: "height"}
  2. The following query demonstrates a merge when there is a key conflict and no resolver function has been provided:

    Value result = await client.Query(
      Merge(
        Obj("f", "First"),
        Obj("f", "Fauna")
      )
    );
    result, err := client.Query(
      f.Merge(
          f.Obj{ "f": "First", },
          f.Obj{ "f": "Fauna", }))
    System.out.println(
      client.query(
        Merge(
          Obj("f", "First"),
          Obj("f", "Fauna")
        )
      ).get());
    client.query(
      q.Merge(
        { f: 'First' },
        { f: 'Fauna' },
      )
    )
    .then((ret) => console.log(ret))
    result = client.query(
      q.merge(
        { "f": "First" },
        { "f": "Fauna" }
      )
    )
    print(result)
    client.query(
      Merge(
        Obj("f" -> "First"),
        Obj("f" -> "Fauna")
     )
    )
    {
      "object": {
        "f": "Fauna"
      }
    }
    map[f:Fauna]
    {f: "Fauna"}
    { f: 'Fauna' }
    {'f': 'Fauna'}
    {f: "Fauna"}
  3. The following query demonstrates a merge when there is a key conflict and a custom resolver function has been provided:

    Value result = await client.Query(
      Merge(
        Obj("c", "Compare", "d", "Difference"),
        Obj("c", "Contrast", "d", "Delta"),
        Lambda(
          Arr("key", "a", "b"),
          If(
            EqualsFn(Var("key"), "c"),
            Var("a"),
            Var("b")
          )
        )
      )
    );
    result, err := client.Query(
      f.Merge(
        f.Obj{ "c": "Compare", "d": "Difference" },
        f.Obj{ "c": "Contrast", "d": "Delta" },
        f.ConflictResolver(
          f.Lambda(
            f.Arr{"key", "a", "b"},
            f.If(
              f.Equals(f.Var("key"), "c"),
              f.Var("a"),
              f.Var("b"))))))
    System.out.println(
      client.query(
        Merge(
          Obj("c", "Compare", "d", "Difference"),
          Obj("c", "Contrast", "d", "Delta"),
          Lambda(
            Arr("key", "a", "b"),
            If(
              Equals(Var("key"), "c"),
              Var("a"),
              Var("b")
            )
          )
        )
      ).get());
    client.query(
      q.Merge(
        { c: 'Compare', d: 'Difference' },
        { c: 'Contrast', d: 'Delta' },
        q.Lambda(
          ['key', 'a', 'b'],
          q.If(
            q.Equals(q.Var('key'), 'c'),
            q.Var('a'),
            q.Var('b'),
          )
        )
      )
    )
    .then((ret) => console.log(ret))
    result = client.query(
      q.merge(
        { "c": "Compare", "d": "Difference" },
        { "c": "Contrast", "d": "Delta" },
        q.lambda_(
          ["key", "a", "b"],
          q.if_(
            q.equals(q.var("key"), "c"),
            q.var("a"),
            q.var("b")
          )
        )
      )
    )
    print(result)
    println(Await.result(
      client.query(
        Merge(
          Obj("c" -> "Compare", "d" -> "Difference"),
          Obj("c" -> "Contrast", "d" -> "Delta"),
          Lambda(
            Arr("key", "a", "b"),
            If(
              Equals(Var("key"), "c"),
              Var("a"),
              Var("b")
            )
          )
        )
      ),
      5.seconds
    ))
    {
      "object": {
        "c": "Compare",
        "d": "Delta"
      }
    }
    map[c:Compare d:Delta]
    {c: "Compare", d: "Delta"}
    { c: 'Compare', d: 'Delta' }
    {'c': 'Compare', 'd': 'Delta'}
    {c: "Compare", d: "Delta"}
  4. The following query demonstrates a merge when an array of objects is provided:

    Value result = await client.Query(
      Merge(
        Obj("c", "Compare", "d", "Difference"),
        Arr(
          Obj("c", "Contrast", "d", "Delta"),
          Obj("a", "Apple", "b", "Banana", "t", "Tomato"),
          Obj("c", "Correlate", "t", "turkey"),
          Obj("d", "disparity")
        )
      )
    );
    result, err := client.Query(
      f.Merge(
          f.Obj{ "c": "Compare", "d": "Difference", },
          f.Arr{
            f.Obj{ "c": "Contrast", "d": "Delta", },
            f.Obj{ "a": "Apple", "b": "Banana", "t": "Tomato" },
            f.Obj{ "c": "Correlate", "t": "turkey" },
            f.Obj{ "d": "disparity" }}))
    System.out.println(
      client.query(
        Merge(
          Obj("c", "Compare", "d", "Difference"),
          Arr(
            Obj("c", "Contrast", "d", "Delta"),
            Obj("a", "Apple", "b", "Banana", "t", "Tomato"),
            Obj("c", "Correlate", "t", "turkey"),
            Obj("d", "disparity"),
          )
        )
      ).get());
    client.query(
      q.Merge(
        { c: 'Compare', d: 'Difference' },
        [
          { c: 'Contrast', d: 'Delta' },
          { a: 'Apple', b: 'Banana', t: 'Tomato' },
          { c: 'Correlate', t: 'turkey' },
          { d: 'disparity' },
        ],
      )
    )
    .then((ret) => console.log(ret))
    result = client.query(
      q.merge(
        { "c": "Compare", "d": "Difference" },
        [
          { "c": "Contrast", "d": "Delta" },
          { "a": "Apple", "b": "Banana", "t": "Tomato" },
          { "c": "Correlate", "t": "turkey" },
          { "d": "disparity" }
        ]
      )
    )
    print(result)
    println(Await.result(
      client.query(
        Merge(
          Obj("c" -> "Compare", "d" -> "Difference"),
          Arr(
            Obj("c" -> "Contrast", "d" -> "Delta"),
            Obj("a" -> "Apple", "b" -> "Banana", "t" -> "Tomato"),
            Obj("c" -> "Correlate", "t" -> "turkey"),
            Obj("d" -> "disparity"),
          )
        )
      ),
      5.seconds
    ))
    {
      "object": {
        "t": "turkey",
        "a": "Apple",
        "b": "Banana",
        "c": "Correlate",
        "d": "disparity"
      }
    }
    map[a:Apple b:Banana c:Correlate d:disparity t:turkey]
    {t: "turkey", a: "Apple", b: "Banana", c: "Correlate", d: "disparity"}
    { t: 'turkey',
      a: 'Apple',
      b: 'Banana',
      c: 'Compare',
      d: 'disparity' }
    {'t': 'turkey', 'a': 'Apple', 'b': 'Banana', 'c': 'Correlate', 'd': 'disparity'}
    {t: "turkey", a: "Apple", b: "Banana", c: "Correlate", d: "disparity"}
  5. The following query demonstrates a merge with a document:

    Value result = await client.Query(
      Merge(
        Get(Ref(Collection("Letters"), 122)),
        Obj("x", 10)
      )
    );
      result, err := client.Query(
        f.Merge(
          f.Get(f.RefCollection(f.Collection("Letters"), 122)),
          f.Obj{ "x": 10 }))
    System.out.println(
        client.query(
            Merge(
                Get(Ref(Collection("Letters"), "122")),
                Obj("x", Value(10))
            )
        ).get()
    );
    client.query(
      q.Merge(
        q.Get(q.Ref(q.Collection('Letters'), 122)),
        { x: 10 },
      )
    )
     .then((ret) => console.log(ret))
    result = client.query(
      q.merge(
        q.get(q.ref(q.collection("Letters"), 122)),
        { "x": 10 }
      )
    )
    print(result)
    println(Await.result(client.query(
        Merge(
          Get(Ref(Collection("Letters"), 122)),
          Obj("x" -> 10),
        )
      ),
      5.seconds))
    {
      "object": {
        "ref": {
          "@ref": {
            "id": "122",
            "collection": {
              "@ref": {
                "id": "Letters",
                "collection": {
                  "@ref": {
                    "id": "collections"
                  }
                }
              }
            }
          }
        },
        "ts": 1566580631370000,
        "data": {
          "object": {
            "letter": "V",
            "extra": "22nd"
          }
        },
        "x": 10
      }
    }
    map[data:map[extra:22nd letter:V] ref:{122 0xc000092b40 0xc000092b40 <nil>} ts:1566580631370000 x:10]
    {ref: ref(id = "122", collection = ref(id = "Letters", collection = ref(id = "collections"))), ts: 1566580631370000, data: {letter: "V", extra: "22nd"}, x: 10}
    { ref: Ref(Collection("Letters"), "122"),
      ts: 1566580631370000,
      data: { letter: 'V', extra: '22nd' },
      x: 10 }
    {'ref': Ref(id=122, collection=Ref(id=Letters, collection=Ref(id=collections))), 'ts': 1566580631370000, 'data': {'letter': 'V', 'extra': '22nd'}, 'x': 10}
    {ref: ref(id = "122", collection = ref(id = "Letters", collection = ref(id = "collections"))), ts: 1566580631370000, data: {letter: "V", extra: "22nd"}, x: 10}
  6. The following query demonstrates a merge with the data field of a document:

    Value result = await client.Query(
      Merge(
        Select("data", Get(Ref(Collection("Letters"), 122))),
        Obj("x", 10)
      )
    );
    result, err := client.Query(
      f.Merge(
        f.Select("data", f.Get(f.RefCollection(f.Collection("Letters"), 122))),
        f.Obj{ "x": 10 }))
    System.out.println(
        client.query(
            Merge(
                Select(Value("data"), Get(Ref(Collection("Letters"), "122"))),
                Obj("x", Value(10))
            )
        ).get()
    );
    client.query(
      q.Merge(
        q.Select('data', q.Get(q.Ref(q.Collection('Letters'), 122))),
        { x: 10 },
      )
    )
     .then((ret) => console.log(ret))
    print(client.query(
      q.merge(
        q.select("data", q.get(q.ref(q.collection("Letters"), 122))),
        { "x": 10 }
      )
    ))
    println(Await.result(client.query(
      Merge(
        Select("data", Get(Ref(Collection("Letters"), 122))),
        Obj("x" -> 10),
      )
    ),
    5.seconds))
    {
      "object": {
        "letter": "V",
        "extra": "22nd",
        "x": 10
      }
    }
    map[extra:22nd letter:V x:10]
    {letter: "V", extra: "22nd", x: 10}
    { letter: 'V', extra: '22nd', x: 10 }
    {'letter': 'V', 'extra': '22nd', 'x': 10}
    {letter: "V", extra: "22nd", x: 10}
  7. The following query demonstrates a merge situation that provides no benefit:

    Value result = await client.Query(
      Merge(
        Obj(),
        Obj("foo", "bar"),
        Lambda(
          Arr("key", "a", "b"),
          Var("a")
        )
      )
    );
    result, err := client.Query(
      f.Merge(
        f.Obj{},
        f.Obj{"foo": "bar"},
        f.ConflictResolver(
          f.Lambda(
            f.Arr{"key", "a", "b"},
            f.Var("a")))))
    
    if (err != nil) {
      fmt.Println(err)
    } else {
      fmt.Println(result)
    }
    System.out.println(
      client.query(
        Merge(
          Obj(),
          Obj("foo", Value("bar")),
          Lambda(
            Arr(Value("key"), Value("a"), Value("b")),
            Var("a")
          )
        )
      ).get());
    client.query(
      q.Merge(
        { },
        { foo: 'bar' },
        q.Lambda(
          ['key', 'a', 'b'],
          q.Var('a')
        )
      )
    )
    .then((ret) => console.log(ret))
    result = client.query(
      q.merge(
        { },
        { "foo": "bar" },
        q.lambda_(
          ["key", "a", "b"],
          q.var("a")
        )
      )
    )
    print(result)
    println(Await.result(
      client.query(
        Merge(
          Obj(),
          Obj("foo" -> "bar"),
          Lambda(
            Arr("key", "a", "b"),
            Var("a")
          )
        )
      ),
      5.seconds
    ))
    ObjectV()
    map[]
    {}
    {}
    {}
    {}

    The customResolver always chooses the value from object1. Since there are no fields in object1, the value returned from customResolver is always null. The null return value means that all of the fields in object2 are removed from object1, which results in an empty object.

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve!
Visit Fauna's Discourse forums or email docs@fauna.com

Thank you for your feedback!