> ## 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, language, 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 fileName = fname ?? sourceUrl.split('/').pop();
return
{code === null ?
Loading...
:
{code}
}
{withSourceLink &&
}
### Vector
Implements a [vector/array](https://en.wikipedia.org/wiki/Array_data_structure) that persists in the contract's storage. See the [Rust SDK collections reference](https://docs.rs/near-sdk/latest/near_sdk/store/index.html) for its complete interface.
### LookupMap
Implements a [map/dictionary](https://en.wikipedia.org/wiki/Associative_array) that persists in the contract's storage. See the [Rust SDK collections reference](https://docs.rs/near-sdk/latest/near_sdk/store/index.html) for its complete interface.
### UnorderedMap / IterableMap
Implements a [map/dictionary](https://en.wikipedia.org/wiki/Associative_array) that persists in the contract's storage. See the [Rust SDK collections reference](https://docs.rs/near-sdk/latest/near_sdk/store/index.html) for its complete interface.
**UnorderedMap vs IterableMap (Rust)**
`UnorderedMap` belongs to the legacy `near_sdk::collections` module. `IterableMap` is its modern replacement in `near_sdk::store`, and should be preferred for new contracts. The `store` collections cache reads and writes within a single transaction, making them more gas-efficient when the same key is accessed multiple times.
### LookupSet
Implements a [set](https://en.wikipedia.org/wiki/Set_\(abstract_data_type\)) that persists in the contract's storage. See the [Rust SDK collections reference](https://docs.rs/near-sdk/latest/near_sdk/store/index.html) for its complete interface.
### UnorderedSet / IterableSet
Implements a [set](https://en.wikipedia.org/wiki/Set_\(abstract_data_type\)) that persists in the contract's storage. See the [Rust SDK collections reference](https://docs.rs/near-sdk/latest/near_sdk/store/index.html) for its complete interface.
**UnorderedSet vs IterableSet**
`UnorderedSet` belongs to the legacy `near_sdk::collections` module. `IterableSet` is its modern replacement in `near_sdk::store`, and should be preferred for new contracts. The `store` collections cache reads and writes within a single transaction, making them more gas-efficient when the same key is accessed multiple times.
### 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.
***
## 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
***
## 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()
}
}
```