> ## Documentation Index
> Fetch the complete documentation index at: https://docs.near.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Collections
> Efficiently store, access, and manage data in smart contracts.
export const Github = ({url, start, end, fname, withSourceLink = true}) => {
const [code, setCode] = useState(null);
function toRaw(ref) {
const fullUrl = ref.slice(ref.indexOf('https'));
const [url] = fullUrl.split('#');
const [org, repo, , branch, ...pathSeg] = new URL(url).pathname.split('/').slice(1);
return `https://raw.githubusercontent.com/${org}/${repo}/${branch}/${pathSeg.join('/')}`;
}
async function fetchCode(url, fromLine, toLine) {
let res;
if (typeof window !== 'undefined') {
const validUntil = localStorage.getItem(`${url}-until`);
if (validUntil && Number(validUntil) > Date.now()) {
res = localStorage.getItem(url);
}
}
if (!res) {
try {
res = await (await fetch(url)).text();
if (typeof window !== 'undefined') {
localStorage.setItem(url, res);
localStorage.setItem(`${url}-until`, String(Date.now() + 60000));
}
} catch {
return 'Error fetching code, please try reloading';
}
}
let body = res.split('\n');
const from = fromLine ? Number(fromLine) - 1 : 0;
const to = toLine ? Number(toLine) : body.length;
body = body.slice(from, to);
const precedingSpace = body.reduce((prev, line) => {
if (line.length === 0) return prev;
const spaces = line.match(/^\s+/);
if (spaces) return Math.min(prev, spaces[0].length);
return 0;
}, Infinity);
return body.map(line => line.slice(precedingSpace === Infinity ? 0 : precedingSpace)).join('\n');
}
function buildSourceUrl(url, start, end) {
const base = url.split('#')[0];
if (start && end) return `${base}#L${start}-L${end}`;
if (start) return `${base}#L${start}`;
return base;
}
useEffect(() => {
const rawUrl = toRaw(url);
fetchCode(rawUrl, start, end).then(res => setCode(res));
}, [url, start, end]);
const sourceUrl = buildSourceUrl(url, start, end);
const startLine = start ? Number(start) : 1;
const fileName = fname ?? sourceUrl.split('/').pop();
return
{}
{start && end &&
Lines {start}–{end}
}
{}
{code === null ?
Loading...
:
{code.split('\n').map((line, i) =>
|
{startLine + i}
|
{line || ' '}
|
)}
}
{}
{withSourceLink &&
}
### Vector
Implements a [vector/array](https://en.wikipedia.org/wiki/Array_data_structure) which persists in the contract's storage. Please refer to the Rust and JS SDK's for a full reference on their interfaces.
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from near_sdk_py import view, call, init
from near_sdk_py.collections import Vector
class VectorExample:
@init
def new(self):
# Create a Vector with prefix "v"
self.my_vector = Vector("v")
@call
def add_number(self, number):
# Append a value to the vector
self.my_vector.append(number)
return len(self.my_vector)
@view
def get_number(self, index):
# Get a value at specific index
try:
return self.my_vector[index]
except Exception:
return None
@view
def get_all_numbers(self):
# Convert entire vector to a list
return [num for num in self.my_vector]
```
### LookupMap
Implements a [map/dictionary](https://en.wikipedia.org/wiki/Associative_array) which persists in the contract's storage. Please refer to the Rust and JS SDK's for a full reference on their interfaces.
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from near_sdk_py import view, call, init
from near_sdk_py.collections import LookupMap
class LookupMapExample:
@init
def new(self):
# Create a LookupMap with prefix "m"
self.balances = LookupMap("m")
@call
def set_balance(self, account_id, amount):
# Set a value for a key
self.balances[account_id] = amount
return True
@view
def get_balance(self, account_id):
# Get a value for a key with a default
return self.balances.get(account_id, 0)
@call
def remove_balance(self, account_id):
# Remove a key
if account_id in self.balances:
del self.balances[account_id]
return True
return False
```
### UnorderedMap / IterableMap
Implements a [map/dictionary](https://en.wikipedia.org/wiki/Associative_array) which persists in the contract's storage. Please refer to the Rust and JS SDK's for a full reference on their interfaces.
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from near_sdk_py import view, call, init
from near_sdk_py.collections import UnorderedMap
class UnorderedMapExample:
@init
def new(self):
# Create an UnorderedMap with prefix "um"
self.user_data = UnorderedMap("um")
@call
def set_user_data(self, account_id, data):
# Set a value for a key
self.user_data[account_id] = data
return True
@view
def get_user_data(self, account_id):
# Get a value for a key
try:
return self.user_data[account_id]
except Exception:
return None
@view
def list_all_users(self):
# Iterate through keys and values
return {
"keys": self.user_data.keys(),
"values": self.user_data.values(),
"items": self.user_data.items()
}
```
### LookupSet
Implements a [set](https://en.wikipedia.org/wiki/Set_\(abstract_data_type\)) which persists in the contract's storage. Please refer to the Rust and JS SDK's for a full reference on their interfaces.
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from near_sdk_py import view, call, init
from near_sdk_py.collections import LookupSet
class LookupSetExample:
@init
def new(self):
# Create a LookupSet with prefix "s"
self.whitelist = LookupSet("s")
@call
def add_to_whitelist(self, account_id):
# Add a value to the set
self.whitelist.add(account_id)
return True
@view
def is_whitelisted(self, account_id):
# Check if a value exists in the set
return account_id in self.whitelist
@call
def remove_from_whitelist(self, account_id):
# Remove a value from the set
try:
self.whitelist.remove(account_id)
return True
except Exception:
return False
```
### UnorderedSet / IterableSet
Implements a [map/dictionary](https://en.wikipedia.org/wiki/Associative_array) which persists in the contract's storage. Please refer to the Rust and JS SDK's for a full reference on their interfaces.
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from near_sdk_py import view, call, init
from near_sdk_py.collections import UnorderedSet
class UnorderedSetExample:
@init
def new(self):
# Create an UnorderedSet with prefix "us"
self.owners = UnorderedSet("us")
@call
def register_owner(self, account_id):
# Add a value to the set
self.owners.add(account_id)
return True
@view
def is_owner(self, account_id):
# Check if a value exists in the set
return account_id in self.owners
@view
def list_all_owners(self):
# Get all values as a list
return self.owners.values()
@call
def remove_owner(self, account_id):
# Try to remove a value if it exists
self.owners.discard(account_id)
return True
```
### Tree
An ordered equivalent of Map. The underlying implementation is based on an [AVL](https://en.wikipedia.org/wiki/AVL_tree). You should use this structure when you need to: have a consistent order, or access the min/max keys.
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from near_sdk_py import view, call, init
from near_sdk_py.collections import TreeMap
class TreeMapExample:
@init
def new(self):
# Create a TreeMap with prefix "tm"
self.scores = TreeMap("tm")
@call
def add_score(self, user_id, score):
# Set score for a user
self.scores[user_id] = score
return True
@view
def get_top_scores(self, limit=10):
# Get top scores using ordered keys
top_users = []
max_key = self.scores.max_key()
current_key = max_key
count = 0
while current_key is not None and count < limit:
top_users.append({
"user": current_key,
"score": self.scores[current_key]
})
current_key = self.scores.floor_key(current_key - 1)
count += 1
return top_users
```
***
## Nesting Collections
When nesting SDK collections, be careful to **use different prefixes** for all collections, including the nested ones.
Notice how we use `enums` that take a `String` argument to ensure all collections have a different prefix
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from near_sdk_py import view, call, init
from near_sdk_py.collections import UnorderedMap, Vector
from near_sdk_py.collections import create_prefix_guard
class NestedCollectionsExample:
@init
def new(self):
# Main map of users to their assets
self.user_assets = UnorderedMap("users")
@call
def add_asset(self, user_id, asset_id, metadata):
# Get or create the user's assets vector with a unique prefix
if user_id not in self.user_assets:
# Create a prefix guard to ensure unique prefixes for this user
prefix = f"assets:{user_id}"
# Create a new vector for this user's assets
self.user_assets[user_id] = Vector(prefix)
# Add the asset to the user's assets vector
user_assets = self.user_assets[user_id]
user_assets.append({
"asset_id": asset_id,
"metadata": metadata
})
# Update the vector in the map
self.user_assets[user_id] = user_assets
return True
@view
def get_user_assets(self, user_id):
if user_id not in self.user_assets:
return []
# Get all assets for the user
user_assets = self.user_assets[user_id]
return [asset for asset in user_assets]
```
In Python, we create unique prefixes for nested collections by including the parent's identifier in the prefix string. The SDK also provides a `create_prefix_guard` utility to help manage prefixes.
In Go, nested `Vector` collections must have their `Len` persisted separately (e.g., in a `LookupMap[string, uint64]`). When reconstructing a vector, pass the saved length via `&collections.Vector[string]{Prefix: prefix, Len: savedLen}`. Always use unique prefixes across all collections.
***
## Error prone patterns
Because the values are not kept in memory and are lazily loaded from storage, it's important to make sure if a collection is replaced or removed, that the storage is cleared. In addition, it is important that if the collection is modified, the collection itself is updated in state because most collections will store some metadata.
Some error-prone patterns to avoid that cannot be restricted at the type level are:
```rust theme={"theme":{"light":"github-light","dark":"github-dark"}}
use near_sdk::store::UnorderedMap;
let mut m = UnorderedMap::::new(b"m");
m.insert(1, "test".to_string());
assert_eq!(m.len(), 1);
assert_eq!(m.get(&1), Some(&"test".to_string()));
// Bug 1: Should not replace any collections without clearing state, this will reset any
// metadata, such as the number of elements, leading to bugs. If you replace the collection
// with something with a different prefix, it will be functional, but you will lose any
// previous data and the old values will not be removed from storage.
m = UnorderedMap::new(b"m");
assert!(m.is_empty());
assert_eq!(m.get(&1), Some(&"test".to_string()));
// Bug 2: Should not use the same prefix as another collection
// or there will be unexpected side effects.
let m2 = UnorderedMap::::new(b"m");
assert!(m2.is_empty());
assert_eq!(m2.get(&1), Some(&"test".to_string()));
// Bug 3: forgetting to save the collection in storage. When the collection is attached to
// the contract state (`self` in `#[near]`) this will be done automatically, but if
// interacting with storage manually or working with nested collections, this is relevant.
use near_sdk::store::Vector;
// Simulate roughly what happens during a function call that initializes state.
{
let v = Vector::::new(b"v");
near_sdk::env::state_write(&v);
}
// Simulate what happens during a function call that just modifies the collection
// but does not store the collection itself.
{
let mut v: Vector = near_sdk::env::state_read().unwrap();
v.push(1);
// The bug is here that the collection itself if not written back
}
let v: Vector = near_sdk::env::state_read().unwrap();
// This will report as if the collection is empty, even though the element exists
assert!(v.get(0).is_none());
assert!(
near_sdk::env::storage_read(&[b"v".as_slice(), &0u32.to_le_bytes()].concat()).is_some()
);
// Bug 4 (only relevant for `near_sdk::store`): These collections will cache writes as well
// as reads, and the writes are performed on [`Drop`](https://doc.rust-lang.org/std/ops/trait.Drop.html)
// so if the collection is kept in static memory or something like `std::mem::forget` is used,
// the changes will not be persisted.
use near_sdk::store::IterableSet;
let mut m: IterableSet = IterableSet::new(b"l");
m.insert(1);
assert!(m.contains(&1));
// This would be the fix, manually flushing the intermediate changes to storage.
// m.flush();
std::mem::forget(m);
m = IterableSet::new(b"l");
assert!(!m.contains(&1));
```
***
## Pagination
Persistent collections such as `IterableMap/UnorderedMap`, `IterableSet/UnorderedSet` and `Vector` may
contain more elements than the amount of gas available to read them all.
In order to expose them all through view calls, we can use pagination.
With Rust this can be done using iterators with [`Skip`](https://doc.rust-lang.org/std/iter/struct.Skip.html) and [`Take`](https://doc.rust-lang.org/std/iter/struct.Take.html). This will only load elements from storage within the range.
```rust theme={"theme":{"light":"github-light","dark":"github-dark"}}
#[near(contract_state)]
#[derive(PanicOnDefault)]
pub struct Contract {
pub status_updates: IterableMap,
}
#[near]
impl Contract {
/// Retrieves multiple elements from the `IterableMap`.
/// - `from_index` is the index to start from.
/// - `limit` is the maximum number of elements to return.
pub fn get_updates(&self, from_index: usize, limit: usize) -> Vec<(AccountId, String)> {
self.status_updates
.iter()
.skip(from_index)
.take(limit)
.collect()
}
}
```
With JavaScript this can be done using iterators with [`toArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Iterator/toArray) and [`slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice).
```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
/// Returns multiple elements from the `UnorderedMap`.
/// - `from_index` is the index to start from.
/// - `limit` is the maximum number of elements to return.
@view({})
get_updates({ from_index, limit }: { from_index: number, limit:number }) {
return this.status_updates.toArray().slice(from_index, limit);
}
```
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# With Python this can be done using standard list slicing.
@view
def get_updates(self, from_index: int = 0, limit: int = 50) -> list:
"""Returns multiple elements from the collection with pagination."""
all_items = self.status_updates.values()
start = min(from_index, len(all_items))
end = min(start + limit, len(all_items))
return all_items[start:end]
```
With Go this can be done using index-based iteration over a `Vector`, loading only the elements within the requested range.