# Object

These functions can be used when working with, and manipulating data objects.

These functions can be used when working with, and manipulating data objects.

<table>
  <thead>
    <tr>
      <th scope="col">Function</th>
      <th scope="col">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td scope="row" data-label="Function"><a href="#objectentries"><code>object::entries()</code></a></td>
      <td scope="row" data-label="Description">Transforms an object into an array with arrays of key-value combinations.</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#objectextend"><code>object::extend()</code></a></td>
      <td scope="row" data-label="Description">Extends an object with the content of another one.</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#objectfrom_entries"><code>object::from_entries()</code></a></td>
      <td scope="row" data-label="Description">Transforms an array with arrays of key-value combinations into an object.</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#objectis_empty"><code>object::is_empty()</code></a></td>
      <td scope="row" data-label="Description">Checks if an object is empty</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#objectkeys"><code>object::keys()</code></a></td>
      <td scope="row" data-label="Description">Returns an array with all the keys of an object.</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#objectlen"><code>object::len()</code></a></td>
      <td scope="row" data-label="Description">Returns the amount of key-value pairs an object holds.</td>
    </tr>
<tr>
      <td scope="row" data-label="Function"><a href="#objectremove"><code>object::remove()</code></a></td>
      <td scope="row" data-label="Description">Removes one or more fields from an object.</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#objectvalues"><code>object::values()</code></a></td>
      <td scope="row" data-label="Description">Returns an array with all the values of an object.</td>
    </tr>
  </tbody>
</table>

## `object::entries`

The `object::entries` function transforms an object into an array with arrays of key-value combinations.

```surql title="API DEFINITION"
object::entries(object) -> array
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN object::entries({
  a: 1,
  b: true
});
```

```surql title="Response"
[
  [ 'a', 1 ],
  [ 'b', true ],
]
```

<br />

## `object::extend`

_(since v3.0.0)_

The `object::extend` function extends an object with the fields and values of another one, essentially adding the two together.

```surql title="API DEFINITION"
object::extend(object, $other: object) -> object
```

An example of the function, resulting in one new field (`gold`) and one updated field (`last_updated`) in the final output.

```surql
{ name: "Mat Cauthon", last_updated: d'2013-01-08'}.extend( 
{ gold: 100, last_updated: time::now() });
```

```surql title="Output"
{
	gold: 100,
	last_updated: d'2025-05-07T06:15:00.768Z',
	name: 'Mat Cauthon'
}
```

Note: the same behaviour can also be achieved using the `+` operator.

```surql
{ name: "Mat Cauthon", last_updated: d'2013-01-08'} + 
{ gold: 100, last_updated: time::now() };
```

<br />

## `object::from_entries`

The `object::from_entries` function transforms an array with arrays of key-value combinations into an object.

```surql title="API DEFINITION"
object::from_entries(array) -> object
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN object::from_entries([
  [ "a", 1 ],
  [ "b", true ],
]);
```

```surql title="Response"
{
  a: 1,
  b: true
}
```

## `object::is_empty`

_(since v2.2.0)_

The `object::is_empty` function checks whether the object contains values.

```surql title="API DEFINITION"
object::is_empty(object) -> bool
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql title="An object that contain values"
RETURN {
  name: "Aeon",
  age: 20
}.is_empty();

-- false
```

```surql title="An empty object"
RETURN object::is_empty({});

-- true
```

Example of `.is_empty()` being used in a [`DEFINE FIELD`](/docs/reference/query-language/statements/define/field.md#asserting-rules-on-fields) statement to disallow empty objects:

```surql
DEFINE FIELD metadata
  ON house
  TYPE object
  ASSERT !$value.is_empty();
CREATE house SET metadata = {};
CREATE house SET metadata = { floors: 5 };
```

```surql title="Output"
-------- Query --------

'Found {  } for field `metadata`, with record `house:aei2fms2jccm46ceib8l`, but field must conform to: !$value.is_empty()'

-------- Query --------

[
	{
		id: house:g126ct3m0scbkockq32u,
		metadata: {
			floors: 5
		}
	}
]
```

## `object::keys`

The `object::keys` function returns an array with all the keys of an object.

```surql title="API DEFINITION"
object::keys(object) -> array
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN object::keys({
  a: 1,
  b: true
});

-- [ 'a', 'b' ]
```

<br />

## `object::len`

The `object::len` function returns the amount of key-value pairs an object holds.

```surql title="API DEFINITION"
object::len(object) -> number
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN object::len({
  a: 1,
  b: true
});

-- 2
```

## `object::remove`

_(since v3.0.0)_

The `object::remove` function removes one or more fields from an object.

```surql title="API DEFINITION"
object::remove(object, $to_remove: string|array<string>) -> object
```

A single string can be used to remove a single field from an object, while an array of strings can be used to remove one or more fields at a time.

```surql
{ name: "Mat Cauthon", last_updated: d'2013-01-08', gold: 100 }.remove("gold");
{ name: "Mat Cauthon", last_updated: d'2013-01-08', gold: 100 }.remove(["gold", "last_updated"]);
```

```surql title="Output"
-------- Query 1 --------

{
	last_updated: d'2013-01-08T00:00:00Z',
	name: 'Mat Cauthon'
}

-------- Query 2 --------

{
	name: 'Mat Cauthon'
}
```

## `object::values`

The `object::values` function returns an array with all the values of an object.

```surql title="API DEFINITION"
object::values(object) -> array
```

The following example shows this function, and its output, when used in a [`RETURN`](/docs/reference/query-language/statements/return.md) statement:

```surql
RETURN object::values({
  a: 1,
  b: true
});

-- [1, true]
```

<br /><br />

## Method chaining

Method chaining allows functions to be called using the `.` dot operator on a value of a certain type instead of the full path of the function followed by the value.

```surql
-- Traditional syntax
object::values({
  a: 1,
  b: true
});

-- Method chaining syntax
{
  a: 1,
  b: true
}.values();
```

```surql title="Response"
[
  1,
  true
]
```

This is particularly useful for readability when a function is called multiple times.

```surql
-- Traditional syntax
array::max(object::values(object::from_entries([["a", 1], ["b", 2]])));

-- Method chaining syntax
object::from_entries([["a", 1], ["b", 2]]).values().max();
```

```surql title="Response"
2
```