# record

::: note
For use-cases that have [`single-bin`](https://aerospike.com/docs/database/reference/config#namespace__single-bin) configuration set to `true`, the bin name is required to be an empty string for reading or writing the bin for versions 3.15 and above. Versions prior to 3.15 do not support UDFs on single-bin namespaces.
:::

A Record is provided by the UDF system and can represent an existing record or an empty record. It provides access to a record’s bins and metadata.

A Record can be accessed much like a Map or Lua Table, where the key can be a String:

```lua
> rec

[ REC ]

> rec['a'] = 1

> rec['a']

1
```

A Record must only contain values of the following types:

-   integer
-   string
-   [bytes](https://aerospike.com/docs/database/8.0.0/advanced/udf/api/types/bytes)
-   [list](https://aerospike.com/docs/database/8.0.0/advanced/udf/api/types/list)
-   [map](https://aerospike.com/docs/database/8.0.0/advanced/udf/api/types/map)

Placing other Lua types - for example, functions or tables - will result in run-time errors.

Changes to an existing Record are not reflected in the database unless you call aerospike:update(rec) to write the Record back to the database.

## Functions

### record.bin\_names()

Get the bin names of a record.

```lua
function record.bin_names(r: Record): Lua table
```

| Parameter | Returns |
| --- | --- |
| `r` – the `Record` to get the bin names of. | A Lua table containing the bin names. This table can be iterated over with the ipairs() function. |

Example:

```lua
> names = record.bin_names(rec)

> for i, name in ipairs(names) do

>   info("bin %d name = %s", i, tostring(name))

> end

bin 1 name = bin1

bin 2 name = bin2

bin 3 name = third bin
```

---

### record.size()

Get the size of a record, in bytes. Available in server 7.0.0 and later.

```lua
function record.size(r: Record): integer
```

| Parameter | Returns |
| --- | --- |
| `r` – the `Record` to get the size of. | The size of the record in bytes. |

Example:

```lua
> record.size(rec)

1480
```

---

### record.device\_size()

::: note
This method was deprecated in server 7.0.0. Use size() instead.
:::

Get the device storage size of a record, in bytes. Available in server 5.2.0 and later.

```lua
function record.device_size(r: Record): integer
```

| Parameter | Returns |
| --- | --- |
| `r` – the `Record` to get the device storage size of. | The device storage size of the record. Note this value will be 0 if using [`storage-engine`](https://aerospike.com/docs/database/reference/config#namespace__storage-engine) memory. |

Example:

```lua
> record.device_size(rec)

1480
```

---

### record.digest()

Get the digest of a record. The digest is the hash of the key and other values using for distributing the record across the cluster.

```lua
function record.digest(r: Record): Bytes
```

| Parameter | Returns |
| --- | --- |
| `r` – the `Record` to get the digest value of. | The digest of the record. |

Example:

```lua
> record.digest(rec)

Bytes(68656c6c6f20776f726c64)
```

---

### record.gen()

Get the generation value of a record. The generation values is equivalent to a revision number.

```lua
function record.gen(r: Record): Integer
```

| Parameter | Returns |
| --- | --- |
| `r` – the `Record` to get the generation value of. | The generation of the record. |

Example:

```lua
> record.gen(rec)

5
```

---

### record.key()

Get the key of a record.

```lua
function record.key(r: Record): string
```

| Parameter | Returns |
| --- | --- |
| `r` – the `Record` to get the key value of. | The key of the record. Returns nil if the record’s key is not stored. |

Example:

```lua
> record.key(rec)

my-key
```

---

### record.last\_update\_time()

Get the last update time of a record. Available in server 3.8.3 and later.

```lua
function record.last_update_time(r: Record): integer
```

| Parameter | Returns |
| --- | --- |
| `r` – the `Record` to get the last update time of. | The last update time of the record, expressed in milliseconds since the Citrusleaf epoch (00:00:00 UTC on 1 Jan 2010). |

Example:

```lua
> record.last_update_time(rec)

226179209266
```

---

### record.memory\_size()

::: note
This method was deprecated in server 7.0.0. Use [`size()`](https://aerospike.com/docs/database/8.0.0/advanced/udf/api/types/record/#recordsize) instead.
:::

Get the in-memory size of a record, in bytes. Available in server version 5.3.0 and later.

```lua
function record.memory_size(r: Record): integer
```

| Parameter | Returns |
| --- | --- |
| `r` – the `Record` to get the memory size of. | The memory size of the record. Note this value will be 0 unless either [`storage-engine`](https://aerospike.com/docs/database/reference/config#namespace__storage-engine) is `memory` or [`data-in-memory`](https://aerospike.com/docs/database/reference/config#namespace__data-in-memory) is `true`. |

Example:

```lua
> record.memory_size(rec)

1350
```

---

### record.numbins()

Get the number of bins in a record.

```lua
function record.numbins(r: Record): integer
```

| Parameter | Returns |
| --- | --- |
| `r` – the `Record` to get the number of bins of. | The number of bins in the record. Returns 1 if the record belongs to a single-bin namespace. |

Example:

```lua
> record.numbins(rec)

7
```

---

### record.setname()

Get the set name of a record.

```lua
function record.setname(r: Record): string
```

| Parameter | Returns |
| --- | --- |
| `r` – the `Record` to get the set name of. | The set name of the record. Returns nil if the record does not belong to a set. |

Example:

```lua
> record.setname(rec)

my-set
```

---

### record.ttl()

Get the time-to-live (ttl) of a record

```lua
function record.ttl(r: Record): Integer
```

| Parameter | Returns |
| --- | --- |
| `r` – the `Record` to get the time-to-live (ttl) value of. | The ttl of the record, in seconds. |

Example:

```lua
> record.ttl(rec)

40000
```

---

### record.set\_ttl()

Set the time-to-live (ttl) of a record. When the record is updated this ttl will take effect.

```lua
function record.set_ttl(r: Record, ttl: Integer): nil
```

| Parameter | Returns |
| --- | --- |
| `r` – the `Record` to set the time-to-live (ttl) value of. | `ttl` – the time-to-live value in seconds. |

Example:

```lua
> record.set_ttl(rec, 10)
```

::: caution
Known issue: reading the ttl within the same UDF transaction context does not return the updated ttl even though set\_ttl() and update() are called. Subsequent transaction calls will correctly return the ttl.
:::

---

### record.drop\_key()

Discard a record’s key. When the record is updated its key will no longer be stored.

```lua
function record.drop_key(r: Record): nil
```

Parameters

-   `r` – the `Record` whose key is to be dropped.

Example:

```lua
> record.drop_key(rec)
```