ligo/gitlab-pages/docs/reference/big_map.md

id	title	description	hide_table_of_contents
big-map-reference	Big_map	A lazily deserialized map that's intended to store large amounts of data.	true

import Syntax from '@theme/Syntax'; import SyntaxTitle from '@theme/SyntaxTitle';

A lazily deserialized map that's intended to store large amounts of data.

The gast costs of deserialized maps are higher than standard maps as data is lazily deserialized.

type big_map (key, value) type ('key, 'value) big_map type big_map ('key, 'value)

The type of a big map from values of type key to values of type value is big_map (key, value).

type move is int * int
type register is big_map (address, move)

The type of a big map from values of type key to values of type value is (key, value) big_map.

type move = int * int
type register = (address, move) big_map

The type of a big map from values of type `key` to values of type `value` is `big_map (key, value)`.

type move = (int, int);
type register = big_map (address, move);

function empty : big_map (key, value) val empty : ('key, 'value) big_map let empty: big_map ('key, 'value)

Create an empty big_map.

const empty : register = Big_map.empty

Alternatively, you can also create an empty big_map using:

const empty_alternative : register = big_map []

let empty : register = Big_map.empty

let empty : register = Big_map.empty

function literal : list (key * value) -> big_map (key, value) val literal : ('key * 'value) list -> ('key, 'value) big_map let literal: list(('key, 'value)) => big_map('key, 'value)

Create a non-empty big_map.

const moves : register =
  Big_map.literal (list [
    (("tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx" : address), (1,2));
    (("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address), (0,3))]);

Alternative way of creating an empty big_map:

const moves_alternative : register =
  big_map [
    ("tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx" : address) -> (1,2);
    ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address) -> (0,3)];

let moves : register =
  Big_map.literal [
    (("tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx" : address), (1,2));
    (("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address), (0,3))]

let moves : register =
  Big_map.literal ([
    ("tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx" : address, (1,2)),
    ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address, (0,3))]);

function find_opt : key -> big_map (key, value) -> option value val find_opt : 'key -> ('key, 'value) big_map -> 'value option let find_opt : ('key, big_map ('key, 'value)) => option ('value)

Retrieve a value from a big map with the given key.

Because the key may be missing in the big map, the result is an optional value.

const my_balance : option (move) =
  Big_map.find_opt (("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address), moves)

Alternatively:

const my_balance_alternative : option (move) =
  moves [("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address)];

let my_balance : move option =
  Big_map.find_opt ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address) moves

let my_balance : option (move) =
  Big_map.find_opt ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address, moves);

function update : key -> option value -> big_map (key, value) -> big_map (key, value) val update: 'key -> 'value option -> ('key, 'value) big_map -> ('key, 'value) big_map let update: ('key, option('value), big_map ('key, 'value)) => big_map ('key, 'value)

Note: when None is used as a value, the value is removed from the big_map.

  const updated_big_map : register = Big_map.update(("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address), Some (4,9), moves);

Alternatively:

function update (var m : register) : register is
  block {
    m [("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address)] := (4,9);
  } with m
  

If multiple bindings need to be updated, PascaLIGO offers a patch instruction for maps, similar to that for records.

function assignments (var m : register) : register is
  block {
    patch m with map [
      ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address) -> (4,9);
      ("tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx" : address) -> (1,2)
    ]
  } with m

Note the use of the keyword map instead of big_map (which is not a keyword).

let updated_map : register =
  Big_map.update
    ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address) (Some (4,9)) moves

let updated_map : register =
  Big_map.update
    (("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address), Some ((4,9)), moves);

function add : key -> value -> big_map (key, value) -> big_map (key, value) val add : 'key -> 'value -> ('key, 'value) big_map -> ('key, 'value) big_map let add: ('key, 'value, big_map('key, 'value)) => big_map('key, 'value)

const added_item : register = Big_map.add (("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address), (4, 9), moves)

let add (m : register) : register =
  Big_map.add
    ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address) (4,9) m

let add = (m: register): register =>
  Big_map.add
    (("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" : address), (4,9), m);

function remove: key -> big_map (key, value) -> big_map (key, value) val remove: 'key -> ('key, 'value) big_map -> ('key, 'value) big_map let remove: (key, big_map ('key, 'value)) => big_map ('key, 'value)

  const updated_map : register = 
    Big_map.remove (("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address), moves)

Alternatively, the instruction remove key from map m removes the key key from the big map m (note that the keyword is map, not big_map).

function rem (var m : register) : register is
  block {
    remove ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address) from map moves
  } with m

const updated_map : register = rem (moves)

let updated_map : register =
  Big_map.remove ("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address) moves

let updated_map : register =
  Big_map.remove (("tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN": address), moves)