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. Lazily means that storage is read or written per key on demand. Therefore there are no map, fold, and iter operations as in Map.

The gast costs of big 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);

Be aware that a big_map cannot appear inside another big_map.

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)