

Shards — shards v1.1.0

 try {

 var settings = JSON.parse(localStorage.getItem('ex\_doc:settings') || '{}');

 if (settings.theme === 'dark' ||

 ((settings.theme === 'system' || settings.theme == null) &&

 window.matchMedia('(prefers-color-scheme: dark)').matches)

 ) {

 document.body.classList.add('dark')

 }

 } catch (error) { }

 

Settings

[View Source](https://github.com/cabol/shards/blob/v1.1.0/README.md#L1 "View Source")

Shards

=========================================================================================================

> ### 

> [ets-tables-on-steroids](#ets-tables-on-steroids)

>  ETS tables on steroids!

> 

> 

> Sharding for ETS tables out-of-box.

> 

> 

![CI](https://github.com/cabol/shards/workflows/CI/badge.svg)

[![Codecov](https://codecov.io/gh/cabol/shards/branch/master/graphs/badge.svg)](https://codecov.io/gh/cabol/shards/branch/master/graphs/badge.svg)

[![Hex Version](https://img.shields.io/hexpm/v/shards.svg)](https://hex.pm/packages/shards)

[![Docs](https://img.shields.io/badge/docs-hexpm-blue.svg)](https://hexdocs.pm/shards)

[![License](https://img.shields.io/hexpm/l/shards.svg)](license.html)

Why might we need **Sharding/Partitioning** for the ETS tables? The main reason

is to keep the lock contention under control enabling ETS tables to scale out

and support higher levels of concurrency without lock issues; specially

write-locks, which most of the cases might cause significant performance

degradation.

Therefore, one of the most common and proven strategies to deal with these

problems is [Sharding](https://en.wikipedia.org/wiki/Shard_(database_architecture)) or [Partitioning](https://en.wikipedia.org/wiki/Partition_(database)); the principle

is pretty similar to [DHTs](https://en.wikipedia.org/wiki/Distributed_hash_table).

This is where [shards](https://hexdocs.pm/shards/shards.html) comes in. [Shards](https://hexdocs.pm/shards/shards.html) is an Erlang/Elixir

library fully compatible with the [ETS API](http://erlang.org/doc/man/ets.html), but it implements sharding

or partitioning on top of the ETS tables, completely transparent and out-of-box.

See the **[getting started](https://hexdocs.pm/shards/getting-started.html)** guide

and the **[online documentation](https://hexdocs.pm/shards/)**.

[installation](#installation)

 Installation

--------------------------------------------

### 

[erlang](#erlang)

 Erlang

In your `rebar.config`:

```

{deps, [

 {shards, "1.1.0"}

]}.

```

### 

[elixir](#elixir)

 Elixir

In your `mix.exs`:

```

def deps do

 [{:shards, "~> 1.1"}]

end

```

> For more information and examples, see the [getting started](https://hexdocs.pm/shards/getting-started.html)

> guide.

> 

> 

[important-links](#important-links)

 Important links

-----------------------------------------------------

* [Blog Post](http://cabol.github.io/posts/2016/04/14/sharding-support-for-ets.html) -

Transparent and out-of-box sharding support for ETS tables in Erlang/Elixir.

* Projects using **shards**:

	+ [shards\_dist](https://github.com/cabol/shards_dist) - Distributed version

	of `shards`. It was moved to a separate repo since `v1.0.0`.

	+ [Nebulex](https://github.com/cabol/nebulex) – Distributed Caching

	framework for Elixir.

	+ [ExShards](https://github.com/cabol/ex_shards) – Elixir wrapper for

	`shards`; with extra and nicer functions.

	+ [KVX](https://github.com/cabol/kvx) – Simple Elixir in-memory Key/Value

	Store using `shards` (default adapter).

	+ [Cacherl](https://github.com/ferigis/cacherl) Distributed Cache

	using `shards`.

[testing](#testing)

 Testing

-----------------------------

```

$ make test

```

You can find tests results in `_build/test/logs`, and coverage in

`_build/test/cover`.

> **NOTE:** `shards` comes with a helper `Makefile`, but it is just a simple

> wrapper on top of `rebar3`, therefore, you can do everything using `rebar3`

> directly as well (e.g.: `rebar3 do ct, cover`).

> 

> 

[generating-edoc](#generating-edoc)

 Generating Edoc

-----------------------------------------------------

```

$ make docs

```

> **NOTE:** Once you run the previous command, you will find the generated HTML

> documentation within `doc` folder; open `doc/index.html`.

> 

> 

[contributing](#contributing)

 Contributing

--------------------------------------------

Contributions to **shards** are very welcome and appreciated!

Use the [issue tracker](https://github.com/cabol/shards/issues) for bug reports

or feature requests. Open a [pull request](https://github.com/cabol/shards/pulls)

when you are ready to contribute.

When submitting a pull request you should not update the [CHANGELOG.md](changelog.html),

and also make sure you test your changes thoroughly, include unit tests

alongside new or changed code.

Before to submit a PR it is highly recommended to run `make check` before and

ensure all checks run successfully.

[copyright-and-license](#copyright-and-license)

 Copyright and License

-----------------------------------------------------------------------

Copyright (c) 2016 Carlos Andres Bolaños R.A.

**Shards** source code is licensed under the [MIT License](license.html).

[← Previous Page

 

Getting Started](getting-started.html)

[Next Page →

 

Changelog](changelog.html)





shards — shards v1.1.0

 try {

 var settings = JSON.parse(localStorage.getItem('ex\_doc:settings') || '{}');

 if (settings.theme === 'dark' ||

 ((settings.theme === 'system' || settings.theme == null) &&

 window.matchMedia('(prefers-color-scheme: dark)').matches)

 ) {

 document.body.classList.add('dark')

 }

 } catch (error) { }

 

Settings

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L94 "View Source")

shards

(shards v1.1.0)

===============================================================================================================================

Partitioned/Sharded ETS tables.

[features](#module-features)

 Features

---------------------------------------

* `shards` implements the ETS API to keep compatibility and make the usage straightforward; exactly the same if you were using `ets`.

* Sharded or partitioned tables under-the-hood. This feature is managed entirely by `shards` and it is 100% transparent for the client. Provides a logical view of a single ETS table, but internally, it is composed by `N` number of `partitions` and each partition has associated an ETS table.

* High performance and scalability. `shards` keeps the lock contention under control enabling ETS tables to scale out and support higher levels of concurrency without lock issues; specially write-locks, which most of the cases might cause significant performance degradation.

[partitioned-table](#module-partitioned-table)

 Partitioned Table

------------------------------------------------------------------

When a table is created with `shards:new/2`, a new supervision tree is created to represent the partitioned table. There is a main supervisor `shards_partition_sup` that create an ETS table to store the metadata and also starts the children which are the partitions to create. Each partition is owned by `shards_partition` (it is a `gen_server`) and it creates an ETS table for storing data mapped to that partition. The supervision tree looks like:

  

```

 [shards\_partition]--><ETS-Table>

 /

 [shards\_partition\_sup]--<-[shards\_partition]--><ETS-Table>

 | \

 <Metadata-ETS-Table> [shards\_partition]--><ETS-Table>

```

  

The returned value by `shards:new/2` may be an atom if it is a named table or a reference otherwise, and in the second case the returned reference is the one of the metadata table, which is the main entry point and it is owned by the main supervisor. See `shards:new/2` for more information.

[usage](#module-usage)

 Usage

------------------------------

```

 > Tab = shards:new(tab, []).

 #Ref<0.1541908042.2337144842.31535>

 > shards:insert(Tab, [{a, 1}, {b, 2}, {c, 3}]).

 true

 > shards:lookup(Tab, a).

 [{a,1}]

 > shards:lookup(Tab, b).

 [{b,2}]

 > shards:lookup(Tab, c).

 [{c,3}]

 > shards:lookup\_element(Tab, c, 2).

 3

 > shards:lookup(Tab, d).

 []

 > shards:delete(Tab, c).

 true

 > shards:lookup(Tab, c).

 []

```

As you can see, the usage is exactly the same if you were using `ets`, you can try the rest of the ETS API but with `shards` module.

[important](#module-important)

 Important

------------------------------------------

Despite `shards` aims to keep 100% compatibility with current ETS API, the semantic for some of the functions may be a bit different due to the nature of sharding; it is not the same having all the entries in a single table than distributed across multiple ones. For example, for query-based functions like `select`, `match`, etc., the returned entries are the same but not necessary the same order than `ets`. For `first`, `next`, and `last` they behave the similar in the sense by means of them a partitioned table is traversed, so the final result is the same, but the order in which the entries are traversed may be different. Therefore, it is highly recommended to read the documentation of the functions.

 

[Link to this section](#summary)

 Summary

==========================================

[Types](#types)

----------------

[access/0](#t:access/0)

[continuation/0](#t:continuation/0)

[ets\_continuation/0](#t:ets_continuation/0)

[filename/0](#t:filename/0)

[info\_item/0](#t:info_item/0)

[info\_tuple/0](#t:info_tuple/0)

[option/0](#t:option/0)

[shards\_opt/0](#t:shards_opt/0)

[tab/0](#t:tab/0)

[tabinfo\_item/0](#t:tabinfo_item/0)

[tweaks/0](#t:tweaks/0)

[type/0](#t:type/0)

[Functions](#functions)

------------------------

[all()](#all/0)

Equivalent to [ets:all()](https://www.erlang.org/doc/man/ets.html#all-0).

[delete(Tab)](#delete/1)

Equivalent to `ets:delete/1`.*See also:* [ets:delete/1](https://www.erlang.org/doc/man/ets.html#delete-1).

[delete(Tab, Key)](#delete/2)

Equivalent to [delete(Tab, Key, shards\_meta:get(Tab))](#delete/3).

[delete(Tab, Key, Meta)](#delete/3)

Equivalent to `ets:delete/2`.*See also:* [ets:delete/2](https://www.erlang.org/doc/man/ets.html#delete-2).

[delete\_all\_objects(Tab)](#delete_all_objects/1)

Equivalent to [delete\_all\_objects(Tab, shards\_meta:get(Tab))](#delete_all_objects/2).

[delete\_all\_objects(Tab, Meta)](#delete_all_objects/2)

Equivalent to `ets:delete_all_objects/1`.*See also:* [ets:delete\_all\_objects/1](https://www.erlang.org/doc/man/ets.html#delete_all_objects-1).

[delete\_object(Tab, Object)](#delete_object/2)

Equivalent to [delete\_object(Tab, Object, shards\_meta:get(Tab))](#delete_object/3).

[delete\_object(Tab, Object, Meta)](#delete_object/3)

Equivalent to `ets:delete_object/2`.*See also:* [ets:delete\_object/2](https://www.erlang.org/doc/man/ets.html#delete_object-2).

[file2tab(Filename)](#file2tab/1)

Equivalent to [file2tab(Filename, [])](#file2tab/2).

[file2tab(Filename, Options)](#file2tab/2)

Equivalent to `shards:file2tab/2`. Moreover, it restores the supervision tree for the `shards` corresponding to the given file, such as if they had been created using `shards:new/2`.*See also:* [ets:file2tab/2](https://www.erlang.org/doc/man/ets.html#file2tab-2).

[first(Tab)](#first/1)

Equivalent to [first(Tab, shards\_meta:get(Tab))](#first/2).

[first(Tab, Meta)](#first/2)

Equivalent to `ets:first/1`.

[foldl(Fun, Acc, Tab)](#foldl/3)

Equivalent to [foldl(Fun, Acc, Tab, shards\_meta:get(Tab))](#foldl/4).

[foldl(Fun, Acc0, Tab, Meta)](#foldl/4)

Equivalent to `ets:foldl/3`.

[foldr(Fun, Acc, Tab)](#foldr/3)

Equivalent to [foldr(Fun, Acc, Tab, shards\_meta:get(Tab))](#foldr/4).

[foldr(Fun, Acc0, Tab, Meta)](#foldr/4)

Equivalent to `ets:foldr/3`.

[get\_meta(Tab, Key)](#get_meta/2)

Equivalent to [get\_meta(Tab, Key, undefined)](#get_meta/3).

[get\_meta(Tab, Key, Def)](#get_meta/3)

Wrapper for `shards_meta:get/3`.

[i()](#i/0)

Equivalent to [ets:i()](https://www.erlang.org/doc/man/ets.html#i-0).

[info(Tab)](#info/1)

Similar to ets:info/1' but extra information about the partitioned table is added.

[info(Tab, Item)](#info/2)

Equivalent to `ets:info/2`.

[insert(Tab, ObjOrObjs)](#insert/2)

Equivalent to [insert(Tab, ObjOrObjs, shards\_meta:get(Tab))](#insert/3).

[insert(Tab, ObjOrObjs, Meta)](#insert/3)

Equivalent to `ets:insert/2`.

[insert\_new(Tab, ObjOrObjs)](#insert_new/2)

Equivalent to [insert\_new(Tab, ObjOrObjs, shards\_meta:get(Tab))](#insert_new/3).

[insert\_new(Tab, ObjOrObjs, Meta)](#insert_new/3)

Equivalent to `ets:insert_new/2`.

[is\_compiled\_ms(Term)](#is_compiled_ms/1)

Equivalent to [ets:is\_compiled\_ms(Term)](https://www.erlang.org/doc/man/ets.html#is_compiled_ms-1).

[last(Tab)](#last/1)

Equivalent to `ets:last/1`.

[lookup(Tab, Key)](#lookup/2)

Equivalent to [lookup(Tab, Key, shards\_meta:get(Tab))](#lookup/3).

[lookup(Tab, Key, Meta)](#lookup/3)

Equivalent to `ets:lookup/2`.*See also:* [ets:lookup/2](https://www.erlang.org/doc/man/ets.html#lookup-2).

[lookup\_element(Tab, Key, Pos)](#lookup_element/3)

Equivalent to [lookup\_element(Tab, Key, Pos, shards\_meta:get(Tab))](#lookup_element/4).

[lookup\_element(Tab, Key, Pos, Meta)](#lookup_element/4)

Equivalent to `ets:lookup_element/3`.*See also:* [ets:lookup\_element/3](https://www.erlang.org/doc/man/ets.html#lookup_element-3).

[match(Continuation)](#match/1)

Equivalent to `ets:match/1`.

[match(Tab, Pattern)](#match/2)

Equivalent to [match(Tab, Pattern, shards\_meta:get(Tab))](#match/3).

[match(Tab, Pattern, LimitOrMeta)](#match/3)

If 3rd argument is `pos_integer()` this function behaves like `ets:match/3`, otherwise, the 3rd argument is assumed as `shards_meta:t()` and it behaves like `ets:match/2`.

[match(Tab, Pattern, Limit, Meta)](#match/4)

Equivalent to `ets:match/3`.

[match\_delete(Tab, Pattern)](#match_delete/2)

Equivalent to [match\_delete(Tab, Pattern, shards\_meta:get(Tab))](#match_delete/3).

[match\_delete(Tab, Pattern, Meta)](#match_delete/3)

Equivalent to `ets:match_delete/2`.*See also:* [ets:match\_delete/2](https://www.erlang.org/doc/man/ets.html#match_delete-2).

[match\_object(Cont)](#match_object/1)

Equivalent to `ets:match_object/1`.

[match\_object(Tab, Pattern)](#match_object/2)

Equivalent to [match\_object(Tab, Pattern, shards\_meta:get(Tab))](#match_object/3).

[match\_object(Tab, Pattern, LimitOrMeta)](#match_object/3)

If 3rd argument is `pos_integer()` this function behaves like `ets:match_object/3`, otherwise, the 3rd argument is assumed as `shards_meta:t()` and it behaves like `ets:match_object/2`.

[match\_object(Tab, Pattern, Limit, Meta)](#match_object/4)

Equivalent to `ets:match_object/3`.

[match\_spec\_compile(MatchSpec)](#match_spec_compile/1)

Equivalent to [ets:match\_spec\_compile(MatchSpec)](https://www.erlang.org/doc/man/ets.html#match_spec_compile-1).

[match\_spec\_run(List, CompiledMatchSpec)](#match_spec_run/2)

Equivalent to [ets:match\_spec\_run(List, CompiledMatchSpec)](https://www.erlang.org/doc/man/ets.html#match_spec_run-2).

[member(Tab, Key)](#member/2)

Equivalent to [member(Tab, Key, shards\_meta:get(Tab))](#member/3).

[member(Tab, Key, Meta)](#member/3)

Equivalent to `ets:member/2`.*See also:* [ets:member/2](https://www.erlang.org/doc/man/ets.html#member-2).

[new(Name, Options)](#new/2)

This operation is equivalent to `ets:new/2`, but when is called, instead of create a single ETS table, it creates a new supervision tree for the partitioned table.

[next(Tab, Key1)](#next/2)

Equivalent to [next(Tab, Key1, shards\_meta:get(Tab))](#next/3).

[next(Tab, Key1, Meta)](#next/3)

Equivalent to `ets:next/2`.

[partition\_owners(TabOrPid)](#partition_owners/1)

Returns the partition PIDs associated with the given table `TabOrPid`.

[prev(Tab, Key1)](#prev/2)

Equivalent to `ets:next/2`.

[put\_meta(Tab, Key, Val)](#put_meta/3)

Wrapper for `shards_meta:put/3`.

[rename(Tab, Name)](#rename/2)

Equivalent to [rename(Tab, Name, shards\_meta:get(Tab))](#rename/3).

[rename(Tab, Name, Meta)](#rename/3)

Equivalent to `ets:rename/2`.

[safe\_fixtable(Tab, Fix)](#safe_fixtable/2)

Equivalent to [safe\_fixtable(Tab, Fix, shards\_meta:get(Tab))](#safe_fixtable/3).

[select(Cont)](#select/1)

Equivalent to `ets:select/1`.

[select(Tab, MatchSpec)](#select/2)

Equivalent to [select(Tab, MatchSpec, shards\_meta:get(Tab))](#select/3).

[select(Tab, MatchSpec, LimitOrMeta)](#select/3)

If 3rd argument is `pos_integer()` this function behaves like `ets:select/3`, otherwise, the 3rd argument is assumed as `shards_meta:t()` and it behaves like `ets:select/2`.

[select(Tab, MatchSpec, Limit, Meta)](#select/4)

Equivalent to `ets:select/3`.

[select\_count(Tab, MatchSpec)](#select_count/2)

Equivalent to [select\_count(Tab, MatchSpec, shards\_meta:get(Tab))](#select_count/3).

[select\_count(Tab, MatchSpec, Meta)](#select_count/3)

Equivalent to `ets:select_count/2`.*See also:* [ets:select\_count/2](https://www.erlang.org/doc/man/ets.html#select_count-2).

[select\_delete(Tab, MatchSpec)](#select_delete/2)

Equivalent to [select\_delete(Tab, MatchSpec, shards\_meta:get(Tab))](#select_delete/3).

[select\_delete(Tab, MatchSpec, Meta)](#select_delete/3)

Equivalent to `ets:select_delete/2`.*See also:* [ets:select\_delete/2](https://www.erlang.org/doc/man/ets.html#select_delete-2).

[select\_replace(Tab, MatchSpec)](#select_replace/2)

Equivalent to [select\_replace(Tab, MatchSpec, shards\_meta:get(Tab))](#select_replace/3).

[select\_replace(Tab, MatchSpec, Meta)](#select_replace/3)

Equivalent to `ets:select_replace/2`.*See also:* [ets:select\_replace/2](https://www.erlang.org/doc/man/ets.html#select_replace-2).

[select\_reverse(Cont)](#select_reverse/1)

Equivalent to `ets:select_reverse/1`.

[select\_reverse(Tab, MatchSpec)](#select_reverse/2)

Equivalent to [select\_reverse(Tab, MatchSpec, shards\_meta:get(Tab))](#select_reverse/3).

[select\_reverse(Tab, MatchSpec, LimitOrMeta)](#select_reverse/3)

If 3rd argument is `pos_integer()` this function behaves like `ets:select_reverse/3`, otherwise, the 3rd argument is assumed as `shards_meta:t()` and it behaves like `ets:select_reverse/2`.

[select\_reverse(Tab, MatchSpec, Limit, Meta)](#select_reverse/4)

Equivalent to `ets:select_reverse/3`.

[setopts(Tab, Opts)](#setopts/2)

Equivalent to [setopts(Tab, Opts, shards\_meta:get(Tab))](#setopts/3).

[setopts(Tab, Opts, Meta)](#setopts/3)

Equivalent to `ets:setopts/2`.

[tab2file(Tab, Filename)](#tab2file/2)

Equivalent to [tab2file(Tab, Filename, [])](#tab2file/3).

[tab2file(Tab, Filename, Options)](#tab2file/3)

Equivalent to `ets:tab2file/3`.

[tab2list(Tab)](#tab2list/1)

Equivalent to [tab2list(Tab, shards\_meta:get(Tab))](#tab2list/2).

[tab2list(Tab, Meta)](#tab2list/2)

Equivalent to `ets:tab2list/1`.*See also:* [ets:tab2list/1](https://www.erlang.org/doc/man/ets.html#tab2list-1).

[tabfile\_info(Filename)](#tabfile_info/1)

Equivalent to `ets:tabfile_info/1`.

[table(Tab)](#table/1)

Equivalent to [table(Tab, [])](#table/2).

[table(Tab, Options)](#table/2)

Equivalent to [table(Tab, Options, shards\_meta:get(Tab))](#table/3).

[table(Tab, Options, Meta)](#table/3)

Similar to `ets:table/2`, but it returns a list of `qlc:query_handle()`; one per partition.*See also:* [ets:table/2](https://www.erlang.org/doc/man/ets.html#table-2).

[table\_meta(Tab)](#table_meta/1)

Returns the metadata associated with the given table `Tab`.

[take(Tab, Key)](#take/2)

Equivalent to [take(Tab, Key, shards\_meta:get(Tab))](#take/3).

[take(Tab, Key, Meta)](#take/3)

Equivalent to `ets:take/2`.*See also:* [ets:take/2](https://www.erlang.org/doc/man/ets.html#take-2).

[test\_ms(Tuple, MatchSpec)](#test_ms/2)

Equivalent to [ets:test\_ms(Tuple, MatchSpec)](https://www.erlang.org/doc/man/ets.html#test_ms-2).

[update\_counter(Tab, Key, UpdateOp)](#update_counter/3)

Equivalent to [update\_counter(Tab, Key, UpdateOp, shards\_meta:get(Tab))](#update_counter/4).

[update\_counter(Tab, Key, UpdateOp, DefaultOrMeta)](#update_counter/4)

Equivalent to `ets:update_counter/4`.

[update\_counter(Tab, Key, UpdateOp, Default, Meta)](#update_counter/5)

Equivalent to `ets:update_counter/4`.*See also:* [ets:update\_counter/4](https://www.erlang.org/doc/man/ets.html#update_counter-4).

[update\_element(Tab, Key, ElementSpec)](#update_element/3)

Equivalent to [update\_element(Tab, Key, ElementSpec, shards\_meta:get(Tab))](#update_element/4).

[update\_element(Tab, Key, ElementSpec, Meta)](#update_element/4)

Equivalent to `ets:update_element/3`.*See also:* [ets:update\_element/3](https://www.erlang.org/doc/man/ets.html#update_element-3).

[Link to this section](#types)

Types

=====================================

[Link to this type](#t:access/0 "Link to this type")

access/0

========

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L166 "View Source")

```

-type access() :: public | protected | private.

```

[Link to this type](#t:continuation/0 "Link to this type")

continuation/0

==============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L241 "View Source")

```

-type continuation() ::

    {Tab :: [tab](#t:tab/0)(),

     MatchSpec :: [ets:match\_spec](https://www.erlang.org/doc/man/ets.html#type-match_spec)(),

     Limit :: pos_integer(),

     Partition :: non_neg_integer(),

     Continuation :: [ets\_continuation](#t:ets_continuation/0)()}.

```

[Link to this type](#t:ets_continuation/0 "Link to this type")

ets\_continuation/0

===================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L168 "View Source")

```

-type ets_continuation() ::

    '$end_of_table' |

    {[tab](#t:tab/0)(), integer(), integer(), [ets:comp\_match\_spec](https://www.erlang.org/doc/man/ets.html#type-comp_match_spec)(), list(), integer()} |

    {[tab](#t:tab/0)(), _, _, integer(), [ets:comp\_match\_spec](https://www.erlang.org/doc/man/ets.html#type-comp_match_spec)(), list(), integer(), integer()}.

```

[Link to this type](#t:filename/0 "Link to this type")

filename/0

==========

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L250 "View Source")

```

-type filename() :: string() | binary() | atom().

```

[Link to this type](#t:info_item/0 "Link to this type")

info\_item/0

============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L214 "View Source")

```

-type info_item() ::

    compressed | fixed | heir | keypos | memory | name | named_table | node | owner | protection |

    safe_fixed | size | stats | type | write_concurrency | read_concurrency | shards.

```

[Link to this type](#t:info_tuple/0 "Link to this type")

info\_tuple/0

=============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L197 "View Source")

```

-type info_tuple() ::

    {compressed, boolean()} |

    {heir, pid() | none} |

    {keypos, pos_integer()} |

    {memory, non_neg_integer()} |

    {name, atom()} |

    {named_table, boolean()} |

    {node, node()} |

    {owner, pid()} |

    {protection, [access](#t:access/0)()} |

    {size, non_neg_integer()} |

    {type, [type](#t:type/0)()} |

    {write_concurrency, boolean()} |

    {read_concurrency, boolean()} |

    {shards, [atom()]}.

```

[Link to this type](#t:option/0 "Link to this type")

option/0

========

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L186 "View Source")

```

-type option() ::

    [type](#t:type/0)() |

    [access](#t:access/0)() |

    named_table |

    {keypos, pos_integer()} |

    {heir, pid(), HeirData :: term()} |

    {heir, none} |

    [tweaks](#t:tweaks/0)() |

    [shards\_opt](#t:shards_opt/0)().

```

[Link to this type](#t:shards_opt/0 "Link to this type")

shards\_opt/0

=============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L180 "View Source")

```

-type shards_opt() ::

    {partitions, pos_integer()} |

    {keyslot_fun, [shards\_meta:keyslot\_fun](shards_meta.html#t:keyslot_fun/0)()} |

    {restore, term(), term()}.

```

[Link to this type](#t:tab/0 "Link to this type")

tab/0

=====

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L163 "View Source")

```

-type tab() :: atom() | [ets:tid](https://www.erlang.org/doc/man/ets.html#type-tid)().

```

[Link to this type](#t:tabinfo_item/0 "Link to this type")

tabinfo\_item/0

===============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L222 "View Source")

```

-type tabinfo_item() ::

    {name, atom()} |

    {type, [type](#t:type/0)()} |

    {protection, [access](#t:access/0)()} |

    {named_table, boolean()} |

    {keypos, non_neg_integer()} |

    {size, non_neg_integer()} |

    {extended_info, [md5sum | object_count]} |

    {version, {Major :: non_neg_integer(), Minor :: non_neg_integer()}} |

    {shards, [atom()]}.

```

[Link to this type](#t:tweaks/0 "Link to this type")

tweaks/0

========

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L174 "View Source")

```

-type tweaks() :: {write_concurrency, boolean()} | {read_concurrency, boolean()} | compressed.

```

[Link to this type](#t:type/0 "Link to this type")

type/0

======

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L167 "View Source")

```

-type type() :: set | ordered_set | bag | duplicate_bag.

```

[Link to this section](#functions)

Functions

=============================================

[Link to this function](#all/0 "Link to this function")

all()

=====

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L309 "View Source")

Equivalent to [ets:all()](https://www.erlang.org/doc/man/ets.html#all-0).

[Link to this function](#delete/1 "Link to this function")

delete(Tab)

===========

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L318 "View Source")

```

-spec delete(Tab :: [tab](#t:tab/0)()) -> true.

```

Equivalent to `ets:delete/1`.*See also:* [ets:delete/1](https://www.erlang.org/doc/man/ets.html#delete-1).

[Link to this function](#delete/2 "Link to this function")

delete(Tab, Key)

================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L325 "View Source")

Equivalent to [delete(Tab, Key, shards\_meta:get(Tab))](#delete/3).

[Link to this function](#delete/3 "Link to this function")

delete(Tab, Key, Meta)

======================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L337 "View Source")

```

-spec delete(Tab, Key, Meta) -> true when Tab :: [tab](#t:tab/0)(), Key :: term(), Meta :: [shards\_meta:t](shards_meta.html#t:t/0)().

```

Equivalent to `ets:delete/2`.*See also:* [ets:delete/2](https://www.erlang.org/doc/man/ets.html#delete-2).

[Link to this function](#delete_all_objects/1 "Link to this function")

delete\_all\_objects(Tab)

=========================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L342 "View Source")

Equivalent to [delete\_all\_objects(Tab, shards\_meta:get(Tab))](#delete_all_objects/2).

[Link to this function](#delete_all_objects/2 "Link to this function")

delete\_all\_objects(Tab, Meta)

===============================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L353 "View Source")

```

-spec delete_all_objects(Tab, Meta) -> true when Tab :: [tab](#t:tab/0)(), Meta :: [shards\_meta:t](shards_meta.html#t:t/0)().

```

Equivalent to `ets:delete_all_objects/1`.*See also:* [ets:delete\_all\_objects/1](https://www.erlang.org/doc/man/ets.html#delete_all_objects-1).

[Link to this function](#delete_object/2 "Link to this function")

delete\_object(Tab, Object)

===========================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L358 "View Source")

Equivalent to [delete\_object(Tab, Object, shards\_meta:get(Tab))](#delete_object/3).

[Link to this function](#delete_object/3 "Link to this function")

delete\_object(Tab, Object, Meta)

=================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L370 "View Source")

```

-spec delete_object(Tab, Object, Meta) -> true

                 when Tab :: [tab](#t:tab/0)(), Object :: tuple(), Meta :: [shards\_meta:t](shards_meta.html#t:t/0)().

```

Equivalent to `ets:delete_object/2`.*See also:* [ets:delete\_object/2](https://www.erlang.org/doc/man/ets.html#delete_object-2).

[Link to this function](#file2tab/1 "Link to this function")

file2tab(Filename)

==================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L376 "View Source")

Equivalent to [file2tab(Filename, [])](#file2tab/2).

[Link to this function](#file2tab/2 "Link to this function")

file2tab(Filename, Options)

===========================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L392 "View Source")

```

-spec file2tab(Filename, Options) -> {ok, Tab} | {error, Reason}

            when

                Filename :: [filename](#t:filename/0)(),

                Tab :: [tab](#t:tab/0)(),

                Options :: [Option],

                Option :: {verify, boolean()},

                Reason :: term().

```

Equivalent to `shards:file2tab/2`. Moreover, it restores the supervision tree for the `shards` corresponding to the given file, such as if they had been created using `shards:new/2`.*See also:* [ets:file2tab/2](https://www.erlang.org/doc/man/ets.html#file2tab-2).

[Link to this function](#first/1 "Link to this function")

first(Tab)

==========

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L421 "View Source")

Equivalent to [first(Tab, shards\_meta:get(Tab))](#first/2).

[Link to this function](#first/2 "Link to this function")

first(Tab, Meta)

================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L436 "View Source")

```

-spec first(Tab, Meta) -> Key | '$end_of_table'

         when Tab :: [tab](#t:tab/0)(), Key :: term(), Meta :: [shards\_meta:t](shards_meta.html#t:t/0)().

```

Equivalent to `ets:first/1`.

However, the order in which results are returned might be not the same as the original ETS function, since it is a sharded table.*See also:* [ets:first/1](https://www.erlang.org/doc/man/ets.html#first-1).

[Link to this function](#foldl/3 "Link to this function")

foldl(Fun, Acc, Tab)

====================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L451 "View Source")

Equivalent to [foldl(Fun, Acc, Tab, shards\_meta:get(Tab))](#foldl/4).

[Link to this function](#foldl/4 "Link to this function")

foldl(Fun, Acc0, Tab, Meta)

===========================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L470 "View Source")

```

-spec foldl(Fun, Acc0, Tab, Meta) -> Acc1

         when

             Fun :: fun((Element :: term(), AccIn) -> AccOut),

             Tab :: [tab](#t:tab/0)(),

             Meta :: [shards\_meta:t](shards_meta.html#t:t/0)(),

             Acc0 :: term(),

             Acc1 :: term(),

             AccIn :: term(),

             AccOut :: term().

```

Equivalent to `ets:foldl/3`.

However, the order in which the entries are traversed may be different since they are distributed across multiple partitions.*See also:* [ets:foldl/3](https://www.erlang.org/doc/man/ets.html#foldl-3).

[Link to this function](#foldr/3 "Link to this function")

foldr(Fun, Acc, Tab)

====================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L474 "View Source")

Equivalent to [foldr(Fun, Acc, Tab, shards\_meta:get(Tab))](#foldr/4).

[Link to this function](#foldr/4 "Link to this function")

foldr(Fun, Acc0, Tab, Meta)

===========================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L493 "View Source")

```

-spec foldr(Fun, Acc0, Tab, Meta) -> Acc1

         when

             Fun :: fun((Element :: term(), AccIn) -> AccOut),

             Tab :: [tab](#t:tab/0)(),

             Meta :: [shards\_meta:t](shards_meta.html#t:t/0)(),

             Acc0 :: term(),

             Acc1 :: term(),

             AccIn :: term(),

             AccOut :: term().

```

Equivalent to `ets:foldr/3`.

However, the order in which the entries are traversed may be different since they are distributed across multiple partitions.*See also:* [ets:foldr/3](https://www.erlang.org/doc/man/ets.html#foldr-3).

[Link to this function](#get_meta/2 "Link to this function")

get\_meta(Tab, Key)

===================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L275 "View Source")

Equivalent to [get\_meta(Tab, Key, undefined)](#get_meta/3).

[Link to this function](#get_meta/3 "Link to this function")

get\_meta(Tab, Key, Def)

========================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L284 "View Source")

```

-spec get_meta(Tab, Key, Def) -> Val when Tab :: [tab](#t:tab/0)(), Key :: term(), Def :: term(), Val :: term().

```

Wrapper for `shards_meta:get/3`.

 

[Link to this function](#i/0 "Link to this function")

i()

===

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L504 "View Source")

Equivalent to [ets:i()](https://www.erlang.org/doc/man/ets.html#i-0).

[Link to this function](#info/1 "Link to this function")

info(Tab)

=========

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L531 "View Source")

```

-spec info(Tab) -> InfoList | undefined

        when Tab :: [tab](#t:tab/0)(), InfoList :: [InfoTuple], InfoTuple :: [info\_tuple](#t:info_tuple/0)().

```

Similar to ets:info/1' but extra information about the partitioned table is added.

[extra-info](#info/1-extra-info)

 Extra Info:

----------------------------------------------

* `{partitions, post_integer()}` - Number of partitions.

* `{keyslot_fun, shards_meta:keyslot_fun()}` - Functions used for compute the keyslot.

* `{parallel, boolean()}` - Whether the parallel mode is enabled or not.

*See also:* [ets:info/1](https://www.erlang.org/doc/man/ets.html#info-1).

[Link to this function](#info/2 "Link to this function")

info(Tab, Item)

===============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L547 "View Source")

```

-spec info(Tab, Item) -> Value | undefined when Tab :: [tab](#t:tab/0)(), Item :: [info\_item](#t:info_item/0)(), Value :: term().

```

Equivalent to `ets:info/2`.

See the added items by `shards:info/1`.*See also:* [ets:info/2](https://www.erlang.org/doc/man/ets.html#info-2).

[Link to this function](#insert/2 "Link to this function")

insert(Tab, ObjOrObjs)

======================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L564 "View Source")

Equivalent to [insert(Tab, ObjOrObjs, shards\_meta:get(Tab))](#insert/3).

[Link to this function](#insert/3 "Link to this function")

insert(Tab, ObjOrObjs, Meta)

============================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L583 "View Source")

```

-spec insert(Tab, ObjOrObjs, Meta) -> true | no_return()

          when Tab :: [tab](#t:tab/0)(), ObjOrObjs :: tuple() | [tuple()], Meta :: [shards\_meta:t](shards_meta.html#t:t/0)().

```

Equivalent to `ets:insert/2`.

Despite this functions behaves exactly the same as `ets:insert/2` and produces the same result, there is a big difference due to the nature of the sharding distribution model, **IT IS NOT ATOMIC**. Therefore, if it fails by inserting an object at some partition, previous inserts execution on other partitions are not rolled back, but an error is raised instead.*See also:* [ets:insert/2](https://www.erlang.org/doc/man/ets.html#insert-2).

[Link to this function](#insert_new/2 "Link to this function")

insert\_new(Tab, ObjOrObjs)

===========================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L591 "View Source")

Equivalent to [insert\_new(Tab, ObjOrObjs, shards\_meta:get(Tab))](#insert_new/3).

[Link to this function](#insert_new/3 "Link to this function")

insert\_new(Tab, ObjOrObjs, Meta)

=================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L624 "View Source")

```

-spec insert_new(Tab, ObjOrObjs, Meta) -> boolean()

              when Tab :: [tab](#t:tab/0)(), ObjOrObjs :: tuple() | [tuple()], Meta :: [shards\_meta:t](shards_meta.html#t:t/0)().

```

Equivalent to `ets:insert_new/2`.

Despite this functions behaves exactly the same as `ets:insert_new/2` and produces the same result, there is a big difference due to the nature of the sharding distribution model, **IT IS NOT ATOMIC**. Opposite to `shards:insert/2`, this function tries to roll-back previous inserts execution on other partitions if it fails by inserting an object at some partition, but there might be race conditions during roll-back execution.

**Example:**

```

 > shards:insert\_new(mytab, {k1, 1}).

 true

 

 > shards:insert\_new(mytab, {k1, 1}).

 false

 

 > shards:insert\_new(mytab, [{k1, 1}, {k2, 2}]).

 false

```

*See also:* [ets:insert\_new/2](https://www.erlang.org/doc/man/ets.html#insert_new-2).

[Link to this function](#is_compiled_ms/1 "Link to this function")

is\_compiled\_ms(Term)

======================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L652 "View Source")

Equivalent to [ets:is\_compiled\_ms(Term)](https://www.erlang.org/doc/man/ets.html#is_compiled_ms-1).

[Link to this function](#last/1 "Link to this function")

last(Tab)

=========

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L666 "View Source")

```

-spec last(Tab) -> Key | '$end_of_table' when Tab :: [tab](#t:tab/0)(), Key :: term().

```

Equivalent to `ets:last/1`.

However, the order in which results are returned might be not the same as the original ETS function, since it is a sharded table.*See also:* [ets:last/1](https://www.erlang.org/doc/man/ets.html#last-1).

[Link to this function](#lookup/2 "Link to this function")

lookup(Tab, Key)

================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L675 "View Source")

Equivalent to [lookup(Tab, Key, shards\_meta:get(Tab))](#lookup/3).

[Link to this function](#lookup/3 "Link to this function")

lookup(Tab, Key, Meta)

======================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L688 "View Source")

```

-spec lookup(Tab, Key, Meta) -> [Object]

          when Tab :: [tab](#t:tab/0)(), Key :: term(), Meta :: [shards\_meta:t](shards_meta.html#t:t/0)(), Object :: tuple().

```

Equivalent to `ets:lookup/2`.*See also:* [ets:lookup/2](https://www.erlang.org/doc/man/ets.html#lookup-2).

[Link to this function](#lookup_element/3 "Link to this function")

lookup\_element(Tab, Key, Pos)

==============================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L693 "View Source")

Equivalent to [lookup\_element(Tab, Key, Pos, shards\_meta:get(Tab))](#lookup_element/4).

[Link to this function](#lookup_element/4 "Link to this function")

lookup\_element(Tab, Key, Pos, Meta)

====================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L707 "View Source")

```

-spec lookup_element(Tab, Key, Pos, Meta) -> Elem

                  when

                      Tab :: [tab](#t:tab/0)(),

                      Key :: term(),

                      Pos :: pos_integer(),

                      Meta :: [shards\_meta:t](shards_meta.html#t:t/0)(),

                      Elem :: term() | [term()].

```

Equivalent to `ets:lookup_element/3`.*See also:* [ets:lookup\_element/3](https://www.erlang.org/doc/man/ets.html#lookup_element-3).

[Link to this function](#match/1 "Link to this function")

match(Continuation)

===================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L770 "View Source")

```

-spec match(Continuation) -> {[Match], [continuation](#t:continuation/0)()} | '$end_of_table'

         when Match :: [term()], Continuation :: [continuation](#t:continuation/0)().

```

Equivalent to `ets:match/1`.

The order in which results are returned might be not the same as the original ETS function.*See also:* [ets:match/1](https://www.erlang.org/doc/man/ets.html#match-1).

[Link to this function](#match/2 "Link to this function")

match(Tab, Pattern)

===================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L712 "View Source")

Equivalent to [match(Tab, Pattern, shards\_meta:get(Tab))](#match/3).

[Link to this function](#match/3 "Link to this function")

match(Tab, Pattern, LimitOrMeta)

================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L733 "View Source")

```

-spec match(Tab, Pattern, LimitOrMeta) -> {[Match], Cont} | '$end_of_table' | [Match]

         when

             Tab :: [tab](#t:tab/0)(),

             Pattern :: [ets:match\_pattern](https://www.erlang.org/doc/man/ets.html#type-match_pattern)(),

             LimitOrMeta :: pos_integer() | [shards\_meta:t](shards_meta.html#t:t/0)(),

             Match :: [term()],

             Cont :: [continuation](#t:continuation/0)().

```

If 3rd argument is `pos_integer()` this function behaves like `ets:match/3`, otherwise, the 3rd argument is assumed as `shards_meta:t()` and it behaves like `ets:match/2`.

The order in which results are returned might be not the same as the original ETS function.*See also:* [ets:match/2](https://www.erlang.org/doc/man/ets.html#match-2), [ets:match/3](https://www.erlang.org/doc/man/ets.html#match-3).

[Link to this function](#match/4 "Link to this function")

match(Tab, Pattern, Limit, Meta)

================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L755 "View Source")

```

-spec match(Tab, Pattern, Limit, Meta) -> {[Match], Cont} | '$end_of_table'

         when

             Tab :: [tab](#t:tab/0)(),

             Pattern :: [ets:match\_pattern](https://www.erlang.org/doc/man/ets.html#type-match_pattern)(),

             Limit :: pos_integer(),

             Meta :: [shards\_meta:t](shards_meta.html#t:t/0)(),

             Match :: [term()],

             Cont :: [continuation](#t:continuation/0)().

```

Equivalent to `ets:match/3`.

The order in which results are returned might be not the same as the original ETS function.*See also:* [ets:match/3](https://www.erlang.org/doc/man/ets.html#match-3).

[Link to this function](#match_delete/2 "Link to this function")

match\_delete(Tab, Pattern)

===========================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L774 "View Source")

Equivalent to [match\_delete(Tab, Pattern, shards\_meta:get(Tab))](#match_delete/3).

[Link to this function](#match_delete/3 "Link to this function")

match\_delete(Tab, Pattern, Meta)

=================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L786 "View Source")

```

-spec match_delete(Tab, Pattern, Meta) -> true

                when Tab :: [tab](#t:tab/0)(), Pattern :: [ets:match\_pattern](https://www.erlang.org/doc/man/ets.html#type-match_pattern)(), Meta :: [shards\_meta:t](shards_meta.html#t:t/0)().

```

Equivalent to `ets:match_delete/2`.*See also:* [ets:match\_delete/2](https://www.erlang.org/doc/man/ets.html#match_delete-2).

[Link to this function](#match_object/1 "Link to this function")

match\_object(Cont)

===================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L849 "View Source")

```

-spec match_object(Cont) -> {[Object], Cont} | '$end_of_table'

                when Object :: tuple(), Cont :: [continuation](#t:continuation/0)().

```

Equivalent to `ets:match_object/1`.

The order in which results are returned might be not the same as the original ETS function.*See also:* [ets:match\_object/1](https://www.erlang.org/doc/man/ets.html#match_object-1).

[Link to this function](#match_object/2 "Link to this function")

match\_object(Tab, Pattern)

===========================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L792 "View Source")

Equivalent to [match\_object(Tab, Pattern, shards\_meta:get(Tab))](#match_object/3).

[Link to this function](#match_object/3 "Link to this function")

match\_object(Tab, Pattern, LimitOrMeta)

========================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L812 "View Source")

```

-spec match_object(Tab, Pattern, LimitOrMeta) -> {[Object], Cont} | '$end_of_table' | [Object]

                when

                    Tab :: [tab](#t:tab/0)(),

                    Pattern :: [ets:match\_pattern](https://www.erlang.org/doc/man/ets.html#type-match_pattern)(),

                    LimitOrMeta :: pos_integer() | [shards\_meta:t](shards_meta.html#t:t/0)(),

                    Object :: tuple(),

                    Cont :: [continuation](#t:continuation/0)().

```

If 3rd argument is `pos_integer()` this function behaves like `ets:match_object/3`, otherwise, the 3rd argument is assumed as `shards_meta:t()` and it behaves like `ets:match_object/2`.

The order in which results are returned might be not the same as the original ETS function.*See also:* [ets:match\_object/3](https://www.erlang.org/doc/man/ets.html#match_object-3).

[Link to this function](#match_object/4 "Link to this function")

match\_object(Tab, Pattern, Limit, Meta)

========================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L834 "View Source")

```

-spec match_object(Tab, Pattern, Limit, Meta) -> {[Object], Cont} | '$end_of_table'

                when

                    Tab :: [tab](#t:tab/0)(),

                    Pattern :: [ets:match\_pattern](https://www.erlang.org/doc/man/ets.html#type-match_pattern)(),

                    Limit :: pos_integer(),

                    Meta :: [shards\_meta:t](shards_meta.html#t:t/0)(),

                    Object :: tuple(),

                    Cont :: [continuation](#t:continuation/0)().

```

Equivalent to `ets:match_object/3`.

The order in which results are returned might be not the same as the original ETS function.*See also:* [ets:match\_object/3](https://www.erlang.org/doc/man/ets.html#match_object-3).

[Link to this function](#match_spec_compile/1 "Link to this function")

match\_spec\_compile(MatchSpec)

===============================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L853 "View Source")

Equivalent to [ets:match\_spec\_compile(MatchSpec)](https://www.erlang.org/doc/man/ets.html#match_spec_compile-1).

[Link to this function](#match_spec_run/2 "Link to this function")

match\_spec\_run(List, CompiledMatchSpec)

=========================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L857 "View Source")

Equivalent to [ets:match\_spec\_run(List, CompiledMatchSpec)](https://www.erlang.org/doc/man/ets.html#match_spec_run-2).

[Link to this function](#member/2 "Link to this function")

member(Tab, Key)

================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L861 "View Source")

Equivalent to [member(Tab, Key, shards\_meta:get(Tab))](#member/3).

[Link to this function](#member/3 "Link to this function")

member(Tab, Key, Meta)

======================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L873 "View Source")

```

-spec member(Tab, Key, Meta) -> boolean() when Tab :: [tab](#t:tab/0)(), Key :: term(), Meta :: [shards\_meta:t](shards_meta.html#t:t/0)().

```

Equivalent to `ets:member/2`.*See also:* [ets:member/2](https://www.erlang.org/doc/man/ets.html#member-2).

[Link to this function](#new/2 "Link to this function")

new(Name, Options)

==================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L944 "View Source")

```

-spec new(Name, Options) -> Tab when Name :: atom(), Options :: [[option](#t:option/0)()], Tab :: [tab](#t:tab/0)().

```

This operation is equivalent to `ets:new/2`, but when is called, instead of create a single ETS table, it creates a new supervision tree for the partitioned table.

The supervision tree is composed by a main supervisor `shards_partition_sup` and `N` number of workers or partitions handled by `shards_partition` (partition owner). Each worker creates an ETS table to handle the partition. Also, the main supervisor `shards_partition_sup` creates an ETS table to keep the metadata for the partitioned table.

Returns an atom if the created table is a named table, otherwise, a reference is returned. In the last case, the returned reference is the one of the metadata table, which is the main entry-point and it is owned by the main supervisor `shards_partition_sup`.

### 

[options](#new/2-options)

 Options:

In addition to the options given by `ets:new/2`, this functions provides the next options:* `{partitions, N}` - Specifies the number of partitions for the sharded table. By default, `N = erlang:system_info(schedulers_online)`.

* `{keyslot_fun, F}` - Specifies the function used to compute the partition where the action will be evaluated. Defaults to `erlang:phash2/2`.

* `{parallel, P}` - Specifies whether `shards` should work in parallel mode or not, for the applicable functions, e.g.: `select`, `match`, etc. By default is set to `false`.

* `{parallel_timeout, T}` - When `parallel` is set to `true`, it specifies the max timeout for a parallel execution. Defaults to `infinity`.

### 

[access](#new/2-access)

 Access:

Currently, only `public` access is supported by `shards:new/2`. Since a partitioned table is started with its own supervision tree when created, it is very tricky to provide `private` or `protected` access since there are multiple partitions (or ETS tables) and they are owned by the supervisor's children, and the supervisor along with their children (or partitions) are managed by `shards` under-the-hood; it is completely transparent for the client.

### 

[examples](#new/2-examples)

 Examples:

```

 > Tab = shards:new(tab1, []).

 #Ref<0.1541908042.2337144842.31535>

 

 > shards:new(tab2, [named\_table]).

 tab2

```

See also the **"Partitioned Table"** section at the module documentation for more information.*See also:* [ets:new/2](https://www.erlang.org/doc/man/ets.html#new-2).

[Link to this function](#next/2 "Link to this function")

next(Tab, Key1)

===============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L983 "View Source")

Equivalent to [next(Tab, Key1, shards\_meta:get(Tab))](#next/3).

[Link to this function](#next/3 "Link to this function")

next(Tab, Key1, Meta)

=====================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L999 "View Source")

```

-spec next(Tab, Key1, Meta) -> Key2 | '$end_of_table'

        when Tab :: [tab](#t:tab/0)(), Key1 :: term(), Key2 :: term(), Meta :: [shards\_meta:t](shards_meta.html#t:t/0)().

```

Equivalent to `ets:next/2`.

However, the order in which results are returned might be not the same as the original ETS function, since it is a sharded table.*See also:* [ets:next/2](https://www.erlang.org/doc/man/ets.html#next-2).

[Link to this function](#partition_owners/1 "Link to this function")

partition\_owners(TabOrPid)

===========================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L299 "View Source")

```

-spec partition_owners(TabOrPid) -> [OwnerPid] when TabOrPid :: pid() | [tab](#t:tab/0)(), OwnerPid :: pid().

```

Returns the partition PIDs associated with the given table `TabOrPid`.

 

[Link to this function](#prev/2 "Link to this function")

prev(Tab, Key1)

===============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1027 "View Source")

```

-spec prev(Tab, Key1) -> Key2 | '$end_of_table' when Tab :: [tab](#t:tab/0)(), Key1 :: term(), Key2 :: term().

```

Equivalent to `ets:next/2`.

However, the order in which results are returned might be not the same as the original ETS function, since it is a sharded table.*See also:* [ets:prev/2](https://www.erlang.org/doc/man/ets.html#prev-2).

[Link to this function](#put_meta/3 "Link to this function")

put\_meta(Tab, Key, Val)

========================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L292 "View Source")

```

-spec put_meta(Tab, Key, Val) -> ok when Tab :: [shards:tab](shards.html#t:tab/0)(), Key :: term(), Val :: term().

```

Wrapper for `shards_meta:put/3`.

 

[Link to this function](#rename/2 "Link to this function")

rename(Tab, Name)

=================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1036 "View Source")

Equivalent to [rename(Tab, Name, shards\_meta:get(Tab))](#rename/3).

[Link to this function](#rename/3 "Link to this function")

rename(Tab, Name, Meta)

=======================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1052 "View Source")

```

-spec rename(Tab, Name, Meta) -> Name when Tab :: [tab](#t:tab/0)(), Name :: atom(), Meta :: [shards\_meta:t](shards_meta.html#t:t/0)().

```

Equivalent to `ets:rename/2`.

Renames the table name and all its associated shard tables. If something unexpected occurs during the process, an exception will be raised.*See also:* [ets:rename/2](https://www.erlang.org/doc/man/ets.html#rename-2).

[Link to this function](#safe_fixtable/2 "Link to this function")

safe\_fixtable(Tab, Fix)

========================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1059 "View Source")

Equivalent to [safe\_fixtable(Tab, Fix, shards\_meta:get(Tab))](#safe_fixtable/3).

[Link to this function](#select/1 "Link to this function")

select(Cont)

============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1137 "View Source")

```

-spec select(Cont) -> {[Match], Cont} | '$end_of_table' when Match :: term(), Cont :: [continuation](#t:continuation/0)().

```

Equivalent to `ets:select/1`.

The order in which results are returned might be not the same as the original ETS function.*See also:* [ets:select/1](https://www.erlang.org/doc/man/ets.html#select-1).

[Link to this function](#select/2 "Link to this function")

select(Tab, MatchSpec)

======================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1080 "View Source")

Equivalent to [select(Tab, MatchSpec, shards\_meta:get(Tab))](#select/3).

[Link to this function](#select/3 "Link to this function")

select(Tab, MatchSpec, LimitOrMeta)

===================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1100 "View Source")

```

-spec select(Tab, MatchSpec, LimitOrMeta) -> {[Match], Cont} | '$end_of_table' | [Match]

          when

              Tab :: [tab](#t:tab/0)(),

              MatchSpec :: [ets:match\_spec](https://www.erlang.org/doc/man/ets.html#type-match_spec)(),

              LimitOrMeta :: pos_integer() | [shards\_meta:t](shards_meta.html#t:t/0)(),

              Match :: term(),

              Cont :: [continuation](#t:continuation/0)().

```

If 3rd argument is `pos_integer()` this function behaves like `ets:select/3`, otherwise, the 3rd argument is assumed as `shards_meta:t()` and it behaves like `ets:select/2`.

The order in which results are returned might be not the same as the original ETS function.*See also:* [ets:select/3](https://www.erlang.org/doc/man/ets.html#select-3).

[Link to this function](#select/4 "Link to this function")

select(Tab, MatchSpec, Limit, Meta)

===================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1122 "View Source")

```

-spec select(Tab, MatchSpec, Limit, Meta) -> {[Match], Cont} | '$end_of_table'

          when

              Tab :: [tab](#t:tab/0)(),

              MatchSpec :: [ets:match\_spec](https://www.erlang.org/doc/man/ets.html#type-match_spec)(),

              Limit :: pos_integer(),

              Meta :: [shards\_meta:t](shards_meta.html#t:t/0)(),

              Match :: term(),

              Cont :: [continuation](#t:continuation/0)().

```

Equivalent to `ets:select/3`.

The order in which results are returned might be not the same as the original ETS function.*See also:* [ets:select/3](https://www.erlang.org/doc/man/ets.html#select-3).

[Link to this function](#select_count/2 "Link to this function")

select\_count(Tab, MatchSpec)

=============================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1141 "View Source")

Equivalent to [select\_count(Tab, MatchSpec, shards\_meta:get(Tab))](#select_count/3).

[Link to this function](#select_count/3 "Link to this function")

select\_count(Tab, MatchSpec, Meta)

===================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1154 "View Source")

```

-spec select_count(Tab, MatchSpec, Meta) -> NumMatched

                when

                    Tab :: [tab](#t:tab/0)(),

                    MatchSpec :: [ets:match\_spec](https://www.erlang.org/doc/man/ets.html#type-match_spec)(),

                    Meta :: [shards\_meta:t](shards_meta.html#t:t/0)(),

                    NumMatched :: non_neg_integer().

```

Equivalent to `ets:select_count/2`.*See also:* [ets:select\_count/2](https://www.erlang.org/doc/man/ets.html#select_count-2).

[Link to this function](#select_delete/2 "Link to this function")

select\_delete(Tab, MatchSpec)

==============================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1160 "View Source")

Equivalent to [select\_delete(Tab, MatchSpec, shards\_meta:get(Tab))](#select_delete/3).

[Link to this function](#select_delete/3 "Link to this function")

select\_delete(Tab, MatchSpec, Meta)

====================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1173 "View Source")

```

-spec select_delete(Tab, MatchSpec, Meta) -> NumDeleted

                 when

                     Tab :: [tab](#t:tab/0)(),

                     MatchSpec :: [ets:match\_spec](https://www.erlang.org/doc/man/ets.html#type-match_spec)(),

                     Meta :: [shards\_meta:t](shards_meta.html#t:t/0)(),

                     NumDeleted :: non_neg_integer().

```

Equivalent to `ets:select_delete/2`.*See also:* [ets:select\_delete/2](https://www.erlang.org/doc/man/ets.html#select_delete-2).

[Link to this function](#select_replace/2 "Link to this function")

select\_replace(Tab, MatchSpec)

===============================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1179 "View Source")

Equivalent to [select\_replace(Tab, MatchSpec, shards\_meta:get(Tab))](#select_replace/3).

[Link to this function](#select_replace/3 "Link to this function")

select\_replace(Tab, MatchSpec, Meta)

=====================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1192 "View Source")

```

-spec select_replace(Tab, MatchSpec, Meta) -> NumReplaced

                  when

                      Tab :: [tab](#t:tab/0)(),

                      MatchSpec :: [ets:match\_spec](https://www.erlang.org/doc/man/ets.html#type-match_spec)(),

                      Meta :: [shards\_meta:t](shards_meta.html#t:t/0)(),

                      NumReplaced :: non_neg_integer().

```

Equivalent to `ets:select_replace/2`.*See also:* [ets:select\_replace/2](https://www.erlang.org/doc/man/ets.html#select_replace-2).

[Link to this function](#select_reverse/1 "Link to this function")

select\_reverse(Cont)

=====================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1255 "View Source")

```

-spec select_reverse(Cont) -> {[Match], Cont} | '$end_of_table'

                  when Cont :: [continuation](#t:continuation/0)(), Match :: term().

```

Equivalent to `ets:select_reverse/1`.

The order in which results are returned might be not the same as the original ETS function.*See also:* [ets:select\_reverse/1](https://www.erlang.org/doc/man/ets.html#select_reverse-1).

[Link to this function](#select_reverse/2 "Link to this function")

select\_reverse(Tab, MatchSpec)

===============================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1198 "View Source")

Equivalent to [select\_reverse(Tab, MatchSpec, shards\_meta:get(Tab))](#select_reverse/3).

[Link to this function](#select_reverse/3 "Link to this function")

select\_reverse(Tab, MatchSpec, LimitOrMeta)

============================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1218 "View Source")

```

-spec select_reverse(Tab, MatchSpec, LimitOrMeta) -> {[Match], Cont} | '$end_of_table' | [Match]

                  when

                      Tab :: [tab](#t:tab/0)(),

                      MatchSpec :: [ets:match\_spec](https://www.erlang.org/doc/man/ets.html#type-match_spec)(),

                      LimitOrMeta :: pos_integer() | [shards\_meta:t](shards_meta.html#t:t/0)(),

                      Match :: term(),

                      Cont :: [continuation](#t:continuation/0)().

```

If 3rd argument is `pos_integer()` this function behaves like `ets:select_reverse/3`, otherwise, the 3rd argument is assumed as `shards_meta:t()` and it behaves like `ets:select_reverse/2`.

The order in which results are returned might be not the same as the original ETS function.*See also:* [ets:select\_reverse/3](https://www.erlang.org/doc/man/ets.html#select_reverse-3).

[Link to this function](#select_reverse/4 "Link to this function")

select\_reverse(Tab, MatchSpec, Limit, Meta)

============================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1240 "View Source")

```

-spec select_reverse(Tab, MatchSpec, Limit, Meta) -> {[Match], Cont} | '$end_of_table'

                  when

                      Tab :: [tab](#t:tab/0)(),

                      MatchSpec :: [ets:match\_spec](https://www.erlang.org/doc/man/ets.html#type-match_spec)(),

                      Limit :: pos_integer(),

                      Meta :: [shards\_meta:t](shards_meta.html#t:t/0)(),

                      Match :: term(),

                      Cont :: [continuation](#t:continuation/0)().

```

Equivalent to `ets:select_reverse/3`.

The order in which results are returned might be not the same as the original ETS function.*See also:* [ets:select\_reverse/3](https://www.erlang.org/doc/man/ets.html#select_reverse-3).

[Link to this function](#setopts/2 "Link to this function")

setopts(Tab, Opts)

==================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1259 "View Source")

Equivalent to [setopts(Tab, Opts, shards\_meta:get(Tab))](#setopts/3).

[Link to this function](#setopts/3 "Link to this function")

setopts(Tab, Opts, Meta)

========================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1276 "View Source")

```

-spec setopts(Tab, Opts, Meta) -> true

           when

               Tab :: [tab](#t:tab/0)(),

               Opts :: Opt | [Opt],

               Opt :: {heir, pid(), HeirData} | {heir, none},

               Meta :: [shards\_meta:t](shards_meta.html#t:t/0)(),

               HeirData :: term().

```

Equivalent to `ets:setopts/2`.

Returns `true` if the function was applied successfully on each partition, otherwise, `false` is returned.*See also:* [ets:setopts/2](https://www.erlang.org/doc/man/ets.html#setopts-2).

[Link to this function](#tab2file/2 "Link to this function")

tab2file(Tab, Filename)

=======================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1282 "View Source")

Equivalent to [tab2file(Tab, Filename, [])](#tab2file/3).

[Link to this function](#tab2file/3 "Link to this function")

tab2file(Tab, Filename, Options)

================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1301 "View Source")

```

-spec tab2file(Tab, Filename, Options) -> ok | {error, Reason}

            when

                Tab :: [tab](#t:tab/0)(),

                Filename :: [filename](#t:filename/0)(),

                Options :: [Option],

                Option :: {extended_info, [md5sum | object_count]} | {sync, boolean()},

                Reason :: term().

```

Equivalent to `ets:tab2file/3`.

This function generates one file per partition using `ets:tab2file/3`, and also generates a master file with the given `Filename` that holds the information of the created partition files so that they can be recovered by calling `ets:file2tab/1,2`.*See also:* [ets:tab2file/3](https://www.erlang.org/doc/man/ets.html#tab2file-3).

[Link to this function](#tab2list/1 "Link to this function")

tab2list(Tab)

=============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1341 "View Source")

Equivalent to [tab2list(Tab, shards\_meta:get(Tab))](#tab2list/2).

[Link to this function](#tab2list/2 "Link to this function")

tab2list(Tab, Meta)

===================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1353 "View Source")

```

-spec tab2list(Tab, Meta) -> [Object] when Tab :: [tab](#t:tab/0)(), Meta :: [shards\_meta:t](shards_meta.html#t:t/0)(), Object :: tuple().

```

Equivalent to `ets:tab2list/1`.*See also:* [ets:tab2list/1](https://www.erlang.org/doc/man/ets.html#tab2list-1).

[Link to this function](#tabfile_info/1 "Link to this function")

tabfile\_info(Filename)

=======================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1367 "View Source")

```

-spec tabfile_info(Filename) -> {ok, TableInfo} | {error, Reason}

                when Filename :: [filename](#t:filename/0)(), TableInfo :: [[tabinfo\_item](#t:tabinfo_item/0)()], Reason :: term().

```

Equivalent to `ets:tabfile_info/1`.

Adds extra information about the partitions.*See also:* [ets:tabfile\_info/1](https://www.erlang.org/doc/man/ets.html#tabfile_info-1).

[Link to this function](#table/1 "Link to this function")

table(Tab)

==========

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1402 "View Source")

Equivalent to [table(Tab, [])](#table/2).

[Link to this function](#table/2 "Link to this function")

table(Tab, Options)

===================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1406 "View Source")

Equivalent to [table(Tab, Options, shards\_meta:get(Tab))](#table/3).

[Link to this function](#table/3 "Link to this function")

table(Tab, Options, Meta)

=========================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1424 "View Source")

```

-spec table(Tab, Options, Meta) -> QueryHandle

         when

             Tab :: [tab](#t:tab/0)(),

             QueryHandle :: [qlc:query\_handle](https://www.erlang.org/doc/man/qlc.html#type-query_handle)(),

             Options :: [Option] | Option,

             Meta :: [shards\_meta:t](shards_meta.html#t:t/0)(),

             Option :: {n_objects, NObjects} | {traverse, TraverseMethod},

             NObjects :: default | pos_integer(),

             MatchSpec :: [ets:match\_spec](https://www.erlang.org/doc/man/ets.html#type-match_spec)(),

             TraverseMethod :: first_next | last_prev | select | {select, MatchSpec}.

```

Similar to `ets:table/2`, but it returns a list of `qlc:query_handle()`; one per partition.*See also:* [ets:table/2](https://www.erlang.org/doc/man/ets.html#table-2).

[Link to this function](#table_meta/1 "Link to this function")

table\_meta(Tab)

================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L272 "View Source")

```

-spec table_meta(Tab :: [tab](#t:tab/0)()) -> [shards\_meta:t](shards_meta.html#t:t/0)().

```

Returns the metadata associated with the given table `Tab`.

 

[Link to this function](#take/2 "Link to this function")

take(Tab, Key)

==============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1432 "View Source")

Equivalent to [take(Tab, Key, shards\_meta:get(Tab))](#take/3).

[Link to this function](#take/3 "Link to this function")

take(Tab, Key, Meta)

====================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1445 "View Source")

```

-spec take(Tab, Key, Meta) -> [Object]

        when Tab :: [tab](#t:tab/0)(), Key :: term(), Meta :: [shards\_meta:t](shards_meta.html#t:t/0)(), Object :: tuple().

```

Equivalent to `ets:take/2`.*See also:* [ets:take/2](https://www.erlang.org/doc/man/ets.html#take-2).

[Link to this function](#test_ms/2 "Link to this function")

test\_ms(Tuple, MatchSpec)

==========================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1428 "View Source")

Equivalent to [ets:test\_ms(Tuple, MatchSpec)](https://www.erlang.org/doc/man/ets.html#test_ms-2).

[Link to this function](#update_counter/3 "Link to this function")

update\_counter(Tab, Key, UpdateOp)

===================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1450 "View Source")

Equivalent to [update\_counter(Tab, Key, UpdateOp, shards\_meta:get(Tab))](#update_counter/4).

[Link to this function](#update_counter/4 "Link to this function")

update\_counter(Tab, Key, UpdateOp, DefaultOrMeta)

==================================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1467 "View Source")

```

-spec update_counter(Tab, Key, UpdateOp, DefaultOrMeta) -> Result | [Result]

                  when

                      Tab :: [tab](#t:tab/0)(),

                      Key :: term(),

                      UpdateOp :: term(),

                      DefaultOrMeta :: tuple() | [shards\_meta:t](shards_meta.html#t:t/0)(),

                      Result :: integer().

```

Equivalent to `ets:update_counter/4`.

If the 4th argument is `shards_meta:t()`, it behaves like `ets:update_counter/3`.*See also:* [ets:update\_counter/4](https://www.erlang.org/doc/man/ets.html#update_counter-4).

[Link to this function](#update_counter/5 "Link to this function")

update\_counter(Tab, Key, UpdateOp, Default, Meta)

==================================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1489 "View Source")

```

-spec update_counter(Tab, Key, UpdateOp, Default, Meta) -> Result | [Result]

                  when

                      Tab :: [tab](#t:tab/0)(),

                      Key :: term(),

                      UpdateOp :: term(),

                      Default :: tuple(),

                      Meta :: [shards\_meta:t](shards_meta.html#t:t/0)(),

                      Result :: integer().

```

Equivalent to `ets:update_counter/4`.*See also:* [ets:update\_counter/4](https://www.erlang.org/doc/man/ets.html#update_counter-4).

[Link to this function](#update_element/3 "Link to this function")

update\_element(Tab, Key, ElementSpec)

======================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1494 "View Source")

Equivalent to [update\_element(Tab, Key, ElementSpec, shards\_meta:get(Tab))](#update_element/4).

[Link to this function](#update_element/4 "Link to this function")

update\_element(Tab, Key, ElementSpec, Meta)

============================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards.erl#L1507 "View Source")

```

-spec update_element(Tab, Key, ElementSpec, Meta) -> boolean()

                  when

                      Tab :: [tab](#t:tab/0)(),

                      Key :: term(),

                      ElementSpec :: {Pos, Value} | [{Pos, Value}],

                      Meta :: [shards\_meta:t](shards_meta.html#t:t/0)().

```

Equivalent to `ets:update_element/3`.*See also:* [ets:update\_element/3](https://www.erlang.org/doc/man/ets.html#update_element-3).





shards\_enum — shards v1.1.0

 try {

 var settings = JSON.parse(localStorage.getItem('ex\_doc:settings') || '{}');

 if (settings.theme === 'dark' ||

 ((settings.theme === 'system' || settings.theme == null) &&

 window.matchMedia('(prefers-color-scheme: dark)').matches)

 ) {

 document.body.classList.add('dark')

 }

 } catch (error) { }

 

Settings

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_enum.erl#L6 "View Source")

shards\_enum

(shards v1.1.0)

=========================================================================================================================================

Provides a set of utilities to work with enumerables.

 

[Link to this section](#summary)

 Summary

==========================================

[Functions](#functions)

------------------------

[map(Fun, Enumerable)](#map/2)

Returns a list where each element is the result of invoking `Fun` on each corresponding element of `Enumerable`.

[pmap(Fun, Enumerable)](#pmap/2)

Equivalent to [pmap(Fun, infinity, Enumerable)](#pmap/3).

[pmap(Fun, Timeout, Enumerable)](#pmap/3)

Similar to `shards_enum:map/2` but it runs in parallel.

[reduce(Fun, Acc0, Enumerable)](#reduce/3)

Invokes `Fun` for each element in the `Enumerable` with the accumulator.

[reduce\_while(Fun, Acc0, Enumerable)](#reduce_while/3)

Reduces enumerable until `Fun` returns `{halt, AccOut}`.

[Link to this section](#functions)

Functions

=============================================

[Link to this function](#map/2 "Link to this function")

map(Fun, Enumerable)

====================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_enum.erl#L34 "View Source")

```

-spec map(Fun, Enumerable) -> [Result]

       when

           Fun :: fun((Elem) -> Result),

           Elem :: term(),

           Result :: term(),

           Enumerable :: [term()] | map() | non_neg_integer().

```

Returns a list where each element is the result of invoking `Fun` on each corresponding element of `Enumerable`.

For maps, the function expects a key-value tuple.

 

[Link to this function](#pmap/2 "Link to this function")

pmap(Fun, Enumerable)

=====================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_enum.erl#L151 "View Source")

Equivalent to [pmap(Fun, infinity, Enumerable)](#pmap/3).

[Link to this function](#pmap/3 "Link to this function")

pmap(Fun, Timeout, Enumerable)

==============================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_enum.erl#L163 "View Source")

```

-spec pmap(Fun, Timeout, Enumerable) -> [Result]

        when

            Fun :: fun((Elem) -> Result),

            Elem :: term(),

            Timeout :: timeout(),

            Result :: term(),

            Enumerable :: [term()] | map() | non_neg_integer().

```

Similar to `shards_enum:map/2` but it runs in parallel.

 

[Link to this function](#reduce/3 "Link to this function")

reduce(Fun, Acc0, Enumerable)

=============================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_enum.erl#L70 "View Source")

```

-spec reduce(Fun, Acc0, Enumerable) -> Acc1

          when

              Fun :: fun((Elem, AccIn) -> AccOut),

              Elem :: term(),

              AccIn :: term(),

              AccOut :: term(),

              Acc0 :: term(),

              Acc1 :: term(),

              Enumerable :: [term()] | map() | non_neg_integer().

```

Invokes `Fun` for each element in the `Enumerable` with the accumulator.

The initial value of the accumulator is `Acc0`. The function is invoked for each element in the enumerable with the accumulator. The result returned by the function is used as the accumulator for the next iteration. The function returns the last accumulator.

 

[Link to this function](#reduce_while/3 "Link to this function")

reduce\_while(Fun, Acc0, Enumerable)

====================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_enum.erl#L116 "View Source")

```

-spec reduce_while(Fun, Acc0, Enumerable) -> Acc1

                when

                    Fun :: fun((Elem, AccIn) -> FunRes),

                    FunRes :: {cont | halt, AccOut},

                    Elem :: term(),

                    AccIn :: term(),

                    AccOut :: term(),

                    Acc0 :: term(),

                    Acc1 :: term(),

                    Enumerable :: [term()] | map() | non_neg_integer().

```

Reduces enumerable until `Fun` returns `{halt, AccOut}`.

The return value for `Fun` is expected to be

* `{cont, AccOut}` to continue the reduction with `AccOut` as the new accumulator or

* `{halt, AccOut}` to halt the reduction

If fun returns `{halt, AccOut}` the reduction is halted and the function returns `AccOut`. Otherwise, if the enumerable is exhausted, the function returns the accumulator of the last `{cont, AccOut}`.

 





shards\_group — shards v1.1.0

 try {

 var settings = JSON.parse(localStorage.getItem('ex\_doc:settings') || '{}');

 if (settings.theme === 'dark' ||

 ((settings.theme === 'system' || settings.theme == null) &&

 window.matchMedia('(prefers-color-scheme: dark)').matches)

 ) {

 document.body.classList.add('dark')

 }

 } catch (error) { }

 

Settings

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_group.erl#L34 "View Source")

shards\_group

(shards v1.1.0)

============================================================================================================================================

This module provides a dynamic supervisor for creating and/or deleting tables dynamically in runtime and as part of an existing supervision tree; any application supervision tree using `shards`.

[usage](#module-usage)

 Usage

------------------------------

To use `shards` and make the creates tables part of your application supervision tree, you have to add to your main supervisor:

```

 % Supervisor init callback

 init(GroupName) ->

 Children = [

 shards\_group:child\_spec(GroupName)

 ],

 

 {ok, {{one\_for\_one, 10, 10}, Children}}.

```

After your application starts, you can create and delete tables like so:

```

 > {ok, Pid, Tab} = shards\_group:new\_table(GroupName, mytab, [named\_table]).

 {ok,<0.194.0>,#Ref<0.3052443831.2753691659.260835>}

 

 > shards\_group:del\_table(GroupName, mytab).

 ok

```

[Link to this section](#summary)

 Summary

==========================================

[Functions](#functions)

------------------------

[child\_spec(Name)](#child_spec/1)

[del\_table(SupRef, Tab)](#del_table/2)

[init(\_)](#init/1)

[new\_table(SupRef, TabName, Options)](#new_table/3)

[start\_link()](#start_link/0)

Equivalent to [start\_link(shards\_group)](#start_link/1).

[start\_link(Name)](#start_link/1)

[start\_table(Name, Opts)](#start_table/2)

[stop(Pid)](#stop/1)

Equivalent to [stop(Pid, 5000)](#stop/2).

[stop(SupRef, Timeout)](#stop/2)

[Link to this section](#functions)

Functions

=============================================

[Link to this function](#child_spec/1 "Link to this function")

child\_spec(Name)

=================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_group.erl#L82 "View Source")

```

-spec child_spec(Name) -> ChildSpec

              when Name :: atom() | undefined, ChildSpec :: [supervisor:child\_spec](https://www.erlang.org/doc/man/supervisor.html#type-child_spec)().

```

[Link to this function](#del_table/2 "Link to this function")

del\_table(SupRef, Tab)

=======================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_group.erl#L103 "View Source")

```

-spec del_table(SupRef, Tab) -> ok | {error, Reason}

             when SupRef :: atom(), Tab :: [shards:tab](shards.html#t:tab/0)(), Reason :: not_found | simple_one_for_one.

```

[Link to this function](#init/1 "Link to this function")

init(\_)

========

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_group.erl#L119 "View Source")

[Link to this function](#new_table/3 "Link to this function")

new\_table(SupRef, TabName, Options)

====================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_group.erl#L96 "View Source")

```

-spec new_table(SupRef, TabName, Options) -> {ok, TabPid, Tab} | {error, Reason}

             when

                 SupRef :: atom() | pid(),

                 TabName :: atom(),

                 Options :: [[shards:option](shards.html#t:option/0)()],

                 TabPid :: pid(),

                 Tab :: [shards:tab](shards.html#t:tab/0)(),

                 Reason :: term().

```

[Link to this function](#start_link/0 "Link to this function")

start\_link()

=============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_group.erl#L58 "View Source")

Equivalent to [start\_link(shards\_group)](#start_link/1).

[Link to this function](#start_link/1 "Link to this function")

start\_link(Name)

=================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_group.erl#L64 "View Source")

```

-spec start_link(Name) -> StartRet

              when Name :: atom() | undefined, StartRet :: {ok, pid()} | {error, term()}.

```

[Link to this function](#start_table/2 "Link to this function")

start\_table(Name, Opts)

========================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_group.erl#L109 "View Source")

[Link to this function](#stop/1 "Link to this function")

stop(Pid)

=========

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_group.erl#L70 "View Source")

Equivalent to [stop(Pid, 5000)](#stop/2).

[Link to this function](#stop/2 "Link to this function")

stop(SupRef, Timeout)

=====================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_group.erl#L76 "View Source")

```

-spec stop(SupRef, Timeout) -> ok when SupRef :: atom() | pid(), Timeout :: timeout().

```





shards\_lib — shards v1.1.0

 try {

 var settings = JSON.parse(localStorage.getItem('ex\_doc:settings') || '{}');

 if (settings.theme === 'dark' ||

 ((settings.theme === 'system' || settings.theme == null) &&

 window.matchMedia('(prefers-color-scheme: dark)').matches)

 ) {

 document.body.classList.add('dark')

 }

 } catch (error) { }

 

Settings

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_lib.erl#L6 "View Source")

shards\_lib

(shards v1.1.0)

=======================================================================================================================================

Common Shards Utilities.

 

[Link to this section](#summary)

 Summary

==========================================

[Types](#types)

----------------

[kv\_list/0](#t:kv_list/0)

[Functions](#functions)

------------------------

[get\_sup\_child(SupPid, Id)](#get_sup_child/2)

Searches the childern of the supervisor `SupPid` for a child whose Nth element compares equal to `Id`.

[keyfind(Key, KVList)](#keyfind/2)

Equivalent to [keyfind(Key, KVList, undefined)](#keyfind/3).

[keyfind(Key, KVList, Default)](#keyfind/3)

Returns the value to the given `Key` or `Default` if it doesn't exist.

[keypop(Key, KVList1)](#keypop/2)

Equivalent to [keypop(Key, KVList1, undefined)](#keypop/3).

[keypop(Key, KVList1, Default)](#keypop/3)

Searches the list of tuples `KVList1` for a tuple whose Nth element compares equal to `Key`. Returns `{Value, KVList2}` if such a tuple is found, otherwise `{Default, KVList1}`. `KVList2` is a copy of `KVList1` where the first occurrence of Tuple has been removed.

[keyupdate(Fun, Keys, TupleList)](#keyupdate/3)

Equivalent to [keyupdate(Fun, Keys, undefined, TupleList)](#keyupdate/4).

[keyupdate(Fun, Keys, Init, KVList1)](#keyupdate/4)

Updates the given `Keys` by the result of calling `Fun(OldValue)`. If `Key` doesn't exist, then `Init` is set.

[object\_key(ObjOrObjs, Meta)](#object_key/2)

Returns the key for the given object or list of objects.

[read\_tabfile(Filename)](#read_tabfile/1)

Reads the file info related to a tabfile saved previously.

[to\_string(Data)](#to_string/1)

Converts the input data to a string.

[write\_tabfile(Filename, Content)](#write_tabfile/2)

Writes to a file a content related to a table.

[Link to this section](#types)

Types

=====================================

[Link to this type](#t:kv_list/0 "Link to this type")

kv\_list/0

==========

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_lib.erl#L23 "View Source")

```

-type kv_list() :: [{term(), term()}].

```

[Link to this section](#functions)

Functions

=============================================

[Link to this function](#get_sup_child/2 "Link to this function")

get\_sup\_child(SupPid, Id)

===========================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_lib.erl#L51 "View Source")

```

-spec get_sup_child(SupPid, Id) -> Child

                 when SupPid :: pid(), Id :: term(), Child :: pid() | undefined | restarting.

```

Searches the childern of the supervisor `SupPid` for a child whose Nth element compares equal to `Id`.

 

[Link to this function](#keyfind/2 "Link to this function")

keyfind(Key, KVList)

====================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_lib.erl#L56 "View Source")

Equivalent to [keyfind(Key, KVList, undefined)](#keyfind/3).

[Link to this function](#keyfind/3 "Link to this function")

keyfind(Key, KVList, Default)

=============================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_lib.erl#L63 "View Source")

```

-spec keyfind(term(), [kv\_list](#t:kv_list/0)(), term()) -> term().

```

Returns the value to the given `Key` or `Default` if it doesn't exist.

 

[Link to this function](#keypop/2 "Link to this function")

keypop(Key, KVList1)

====================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_lib.erl#L95 "View Source")

Equivalent to [keypop(Key, KVList1, undefined)](#keypop/3).

[Link to this function](#keypop/3 "Link to this function")

keypop(Key, KVList1, Default)

=============================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_lib.erl#L110 "View Source")

```

-spec keypop(Key, KVList1, Default) -> {Value, KVList2}

          when

              Key :: term(),

              KVList1 :: [kv\_list](#t:kv_list/0)(),

              Default :: term(),

              Value :: term(),

              KVList2 :: [kv\_list](#t:kv_list/0)().

```

Searches the list of tuples `KVList1` for a tuple whose Nth element compares equal to `Key`. Returns `{Value, KVList2}` if such a tuple is found, otherwise `{Default, KVList1}`. `KVList2` is a copy of `KVList1` where the first occurrence of Tuple has been removed.

 

[Link to this function](#keyupdate/3 "Link to this function")

keyupdate(Fun, Keys, TupleList)

===============================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_lib.erl#L70 "View Source")

Equivalent to [keyupdate(Fun, Keys, undefined, TupleList)](#keyupdate/4).

[Link to this function](#keyupdate/4 "Link to this function")

keyupdate(Fun, Keys, Init, KVList1)

===================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_lib.erl#L83 "View Source")

```

-spec keyupdate(Fun, Keys, Init, KVList1) -> KVList2

             when

                 Fun :: fun((Key :: term(), Value :: term()) -> term()),

                 Keys :: [term()],

                 Init :: term(),

                 KVList1 :: [kv\_list](#t:kv_list/0)(),

                 KVList2 :: [kv\_list](#t:kv_list/0)().

```

Updates the given `Keys` by the result of calling `Fun(OldValue)`. If `Key` doesn't exist, then `Init` is set.

 

[Link to this function](#object_key/2 "Link to this function")

object\_key(ObjOrObjs, Meta)

============================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_lib.erl#L37 "View Source")

```

-spec object_key(ObjOrObjs, Meta) -> term()

              when ObjOrObjs :: tuple() | [tuple()], Meta :: [shards\_meta:t](shards_meta.html#t:t/0)().

```

Returns the key for the given object or list of objects.

 

[Link to this function](#read_tabfile/1 "Link to this function")

read\_tabfile(Filename)

=======================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_lib.erl#L143 "View Source")

```

-spec read_tabfile([shards:filename](shards.html#t:filename/0)()) -> term() | no_return().

```

Reads the file info related to a tabfile saved previously.

 

[Link to this function](#to_string/1 "Link to this function")

to\_string(Data)

================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_lib.erl#L123 "View Source")

```

-spec to_string(Data :: term()) -> string() | no_return().

```

Converts the input data to a string.

 

[Link to this function](#write_tabfile/2 "Link to this function")

write\_tabfile(Filename, Content)

=================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_lib.erl#L153 "View Source")

```

-spec write_tabfile([shards:filename](shards.html#t:filename/0)(), term()) -> ok | {error, term()}.

```

Writes to a file a content related to a table.

 





shards\_meta — shards v1.1.0

 try {

 var settings = JSON.parse(localStorage.getItem('ex\_doc:settings') || '{}');

 if (settings.theme === 'dark' ||

 ((settings.theme === 'system' || settings.theme == null) &&

 window.matchMedia('(prefers-color-scheme: dark)').matches)

 ) {

 document.body.classList.add('dark')

 }

 } catch (error) { }

 

Settings

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L13 "View Source")

shards\_meta

(shards v1.1.0)

==========================================================================================================================================

This module encapsulates the partitioned table metadata.

Different properties must be stored somewhere so `shards` can work properly. Shards perform logic on top of ETS tables, for example, compute the partition based on the `Key` where the action will be applied. To do so, it needs the number of partitions, the function to select the partition, and also the partition identifier to perform the ETS action.

 

[Link to this section](#summary)

 Summary

==========================================

[Types](#types)

----------------

[keyslot\_fun/0](#t:keyslot_fun/0)

[meta\_map/0](#t:meta_map/0)

[partition\_pids/0](#t:partition_pids/0)

[partition\_tids/0](#t:partition_tids/0)

[t/0](#t:t/0)

[Functions](#functions)

------------------------

[ets\_opts(Meta)](#ets_opts/1)

[from\_map(Map)](#from_map/1)

Builds a new `meta` from the given `Map`.

[get(Tab)](#get/1)

Returns the `tab_info` within the metadata.

[get(Tab, Key)](#get/2)

Equivalent to [get(Tab, Key, undefined)](#get/3).

[get(Tab, Key, Def)](#get/3)

Returns the value for the given `Key` in the metadata, or `Def` if `Key` is not set.

[get\_partition\_pids(Tab)](#get_partition_pids/1)

Returns a list with the partition PIDs.

[get\_partition\_tids(Tab)](#get_partition_tids/1)

Returns a list with the partition TIDs.

[init(Name, Opts)](#init/2)

Initializes the metadata ETS table.

[is\_metadata(Meta)](#is_metadata/1)

Returns `true` if `Meta` is a metadata data type, otherwise, `false` is returned.

[keypos(Meta)](#keypos/1)

[keyslot\_fun(Meta)](#keyslot_fun/1)

[lookup(Tab, Key)](#lookup/2)

Returns the value associated to the key `Key` in the metadata table `Tab`. If `Key` is not found, the error `{unknown_table, Tab}` is raised.

[new()](#new/0)

Returns a metadata data type with the default values.

[parallel(Meta)](#parallel/1)

[parallel\_timeout(Meta)](#parallel_timeout/1)

[partitions(Meta)](#partitions/1)

[put(Tab, Key, Val)](#put/3)

Stores the value `Val` under the given key `Key` into the metadata table `Tab`.

[rename(Tab, Name)](#rename/2)

Renames the metadata ETS table.

[tab\_pid(Meta)](#tab_pid/1)

[to\_map(Meta)](#to_map/1)

Converts the given `Meta` into a `map`.

[Link to this section](#types)

Types

=====================================

[Link to this type](#t:keyslot_fun/0 "Link to this type")

keyslot\_fun/0

==============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L67 "View Source")

```

-type keyslot_fun() :: fun((Key :: term(), Range :: pos_integer()) -> non_neg_integer()).

```

[Link to this type](#t:meta_map/0 "Link to this type")

meta\_map/0

===========

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L84 "View Source")

```

-type meta_map() ::

    #{tab_pid => pid(),

      keypos => pos_integer(),

      partitions => pos_integer(),

      keyslot_fun => [keyslot\_fun](#t:keyslot_fun/0)(),

      parallel => boolean(),

      parallel_timeout => timeout(),

      ets_opts => [term()]}.

```

[Link to this type](#t:partition_pids/0 "Link to this type")

partition\_pids/0

=================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L63 "View Source")

```

-type partition_pids() :: [{non_neg_integer(), pid()}].

```

[Link to this type](#t:partition_tids/0 "Link to this type")

partition\_tids/0

=================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L60 "View Source")

```

-type partition_tids() :: [{non_neg_integer(), [ets:tid](https://www.erlang.org/doc/man/ets.html#type-tid)()}].

```

[Link to this type](#t:t/0 "Link to this type")

t/0

===

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L81 "View Source")

```

-type t() :: #meta{}.

```

[Link to this section](#functions)

Functions

=============================================

[Link to this function](#ets_opts/1 "Link to this function")

ets\_opts(Meta)

===============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L290 "View Source")

```

-spec ets_opts([t](#t:t/0)() | [shards:tab](shards.html#t:tab/0)()) -> [term()].

```

[Link to this function](#from_map/1 "Link to this function")

from\_map(Map)

==============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L115 "View Source")

```

-spec from_map(Map :: #{atom() => term()}) -> [t](#t:t/0)().

```

Builds a new `meta` from the given `Map`.

 

[Link to this function](#get/1 "Link to this function")

get(Tab)

========

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L204 "View Source")

```

-spec get(Tab :: [shards:tab](shards.html#t:tab/0)()) -> [t](#t:t/0)() | no_return().

```

Returns the `tab_info` within the metadata.

 

[Link to this function](#get/2 "Link to this function")

get(Tab, Key)

=============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L207 "View Source")

Equivalent to [get(Tab, Key, undefined)](#get/3).

[Link to this function](#get/3 "Link to this function")

get(Tab, Key, Def)

==================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L219 "View Source")

```

-spec get(Tab, Key, Def) -> Val when Tab :: [shards:tab](shards.html#t:tab/0)(), Key :: term(), Def :: term(), Val :: term().

```

Returns the value for the given `Key` in the metadata, or `Def` if `Key` is not set.

 

[Link to this function](#get_partition_pids/1 "Link to this function")

get\_partition\_pids(Tab)

=========================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L239 "View Source")

```

-spec get_partition_pids(Tab :: [shards:tab](shards.html#t:tab/0)()) -> [partition\_pids](#t:partition_pids/0)().

```

Returns a list with the partition PIDs.

 

[Link to this function](#get_partition_tids/1 "Link to this function")

get\_partition\_tids(Tab)

=========================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L233 "View Source")

```

-spec get_partition_tids(Tab :: [shards:tab](shards.html#t:tab/0)()) -> [partition\_tids](#t:partition_tids/0)().

```

Returns a list with the partition TIDs.

 

[Link to this function](#init/2 "Link to this function")

init(Name, Opts)

================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L156 "View Source")

```

-spec init(Name, Opts) -> Tab when Name :: atom(), Opts :: [[shards:option](shards.html#t:option/0)()], Tab :: [shards:tab](shards.html#t:tab/0)().

```

Initializes the metadata ETS table.

 

[Link to this function](#is_metadata/1 "Link to this function")

is\_metadata(Meta)

==================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L146 "View Source")

```

-spec is_metadata(Meta :: term()) -> boolean().

```

Returns `true` if `Meta` is a metadata data type, otherwise, `false` is returned.

 

[Link to this function](#keypos/1 "Link to this function")

keypos(Meta)

============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L260 "View Source")

```

-spec keypos([t](#t:t/0)() | [shards:tab](shards.html#t:tab/0)()) -> pos_integer().

```

[Link to this function](#keyslot_fun/1 "Link to this function")

keyslot\_fun(Meta)

==================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L272 "View Source")

```

-spec keyslot_fun([t](#t:t/0)() | [shards:tab](shards.html#t:tab/0)()) -> [keyslot\_fun](#t:keyslot_fun/0)().

```

[Link to this function](#lookup/2 "Link to this function")

lookup(Tab, Key)

================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L181 "View Source")

```

-spec lookup(Tab, Key) -> term() when Tab :: [shards:tab](shards.html#t:tab/0)(), Key :: term().

```

Returns the value associated to the key `Key` in the metadata table `Tab`. If `Key` is not found, the error `{unknown_table, Tab}` is raised.

 

[Link to this function](#new/0 "Link to this function")

new()

=====

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L109 "View Source")

```

-spec new() -> [t](#t:t/0)().

```

Returns a metadata data type with the default values.

 

[Link to this function](#parallel/1 "Link to this function")

parallel(Meta)

==============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L278 "View Source")

```

-spec parallel([t](#t:t/0)() | [shards:tab](shards.html#t:tab/0)()) -> boolean().

```

[Link to this function](#parallel_timeout/1 "Link to this function")

parallel\_timeout(Meta)

=======================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L284 "View Source")

```

-spec parallel_timeout([t](#t:t/0)() | [shards:tab](shards.html#t:tab/0)()) -> timeout().

```

[Link to this function](#partitions/1 "Link to this function")

partitions(Meta)

================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L266 "View Source")

```

-spec partitions([t](#t:t/0)() | [shards:tab](shards.html#t:tab/0)()) -> pos_integer().

```

[Link to this function](#put/3 "Link to this function")

put(Tab, Key, Val)

==================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L196 "View Source")

```

-spec put(Tab, Key, Val) -> ok when Tab :: [shards:tab](shards.html#t:tab/0)(), Key :: term(), Val :: term().

```

Stores the value `Val` under the given key `Key` into the metadata table `Tab`.

 

[Link to this function](#rename/2 "Link to this function")

rename(Tab, Name)

=================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L171 "View Source")

```

-spec rename(Tab, Name) -> Name when Tab :: [shards:tab](shards.html#t:tab/0)(), Name :: atom().

```

Renames the metadata ETS table.

 

[Link to this function](#tab_pid/1 "Link to this function")

tab\_pid(Meta)

==============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L254 "View Source")

```

-spec tab_pid([t](#t:t/0)() | [shards:tab](shards.html#t:tab/0)()) -> pid().

```

[Link to this function](#to_map/1 "Link to this function")

to\_map(Meta)

=============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_meta.erl#L130 "View Source")

```

-spec to_map([t](#t:t/0)()) -> [meta\_map](#t:meta_map/0)().

```

Converts the given `Meta` into a `map`.

 





shards\_opts — shards v1.1.0

 try {

 var settings = JSON.parse(localStorage.getItem('ex\_doc:settings') || '{}');

 if (settings.theme === 'dark' ||

 ((settings.theme === 'system' || settings.theme == null) &&

 window.matchMedia('(prefers-color-scheme: dark)').matches)

 ) {

 document.body.classList.add('dark')

 }

 } catch (error) { }

 

Settings

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_opts.erl#L6 "View Source")

shards\_opts

(shards v1.1.0)

=========================================================================================================================================

Utilities for parsing the given shards/ets options..

 

[Link to this section](#summary)

 Summary

==========================================

[Functions](#functions)

------------------------

[parse(Opts)](#parse/1)

[Link to this section](#functions)

Functions

=============================================

[Link to this function](#parse/1 "Link to this function")

parse(Opts)

===========

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_opts.erl#L32 "View Source")

```

-spec parse([[shards:option](shards.html#t:option/0)()]) -> [shards\_meta:meta\_map](shards_meta.html#t:meta_map/0)().

```





shards\_partition — shards v1.1.0

 try {

 var settings = JSON.parse(localStorage.getItem('ex\_doc:settings') || '{}');

 if (settings.theme === 'dark' ||

 ((settings.theme === 'system' || settings.theme == null) &&

 window.matchMedia('(prefers-color-scheme: dark)').matches)

 ) {

 document.body.classList.add('dark')

 }

 } catch (error) { }

 

Settings

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_partition.erl#L9 "View Source")

shards\_partition

(shards v1.1.0)

===================================================================================================================================================

Partition Owner.

The partition owner is a `gen_server` that creates and holds the ETS table associated with the partition.

 

[Link to this section](#summary)

 Summary

==========================================

[Functions](#functions)

------------------------

[apply\_ets\_fun(Pid, EtsFun, Args)](#apply_ets_fun/3)

[compute(Key, Meta)](#compute/2)

[handle\_call(Request, From, State)](#handle_call/3)

[handle\_cast(Request, State)](#handle_cast/2)

[handle\_info(Reason, State)](#handle_info/2)

[init(\_)](#init/1)

[pid(Tab, Partition)](#pid/2)

[retrieve\_tab(Pid)](#retrieve_tab/1)

[start\_link(Tab, PartitionedTablePid, PartitionIndex, Options)](#start_link/4)

[stop(Pid)](#stop/1)

Equivalent to [stop(Server, 5000)](#stop/2).

[stop(Pid, Timeout)](#stop/2)

[tid(Tab, Partition)](#tid/2)

[tid(Tab, Key, Meta)](#tid/3)

[Link to this section](#functions)

Functions

=============================================

[Link to this function](#apply_ets_fun/3 "Link to this function")

apply\_ets\_fun(Pid, EtsFun, Args)

==================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_partition.erl#L63 "View Source")

```

-spec apply_ets_fun(Pid :: pid(), EtsFun :: atom(), Args :: [term()]) -> term().

```

[Link to this function](#compute/2 "Link to this function")

compute(Key, Meta)

==================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_partition.erl#L91 "View Source")

```

-spec compute(Key :: term(), Meta :: [shards\_meta:t](shards_meta.html#t:t/0)()) -> non_neg_integer().

```

[Link to this function](#handle_call/3 "Link to this function")

handle\_call(Request, From, State)

==================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_partition.erl#L131 "View Source")

[Link to this function](#handle_cast/2 "Link to this function")

handle\_cast(Request, State)

============================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_partition.erl#L140 "View Source")

[Link to this function](#handle_info/2 "Link to this function")

handle\_info(Reason, State)

===========================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_partition.erl#L144 "View Source")

[Link to this function](#init/1 "Link to this function")

init(\_)

========

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_partition.erl#L101 "View Source")

[Link to this function](#pid/2 "Link to this function")

pid(Tab, Partition)

===================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_partition.erl#L87 "View Source")

```

-spec pid(Tab :: [shards:tab](shards.html#t:tab/0)(), Partition :: non_neg_integer()) -> pid().

```

[Link to this function](#retrieve_tab/1 "Link to this function")

retrieve\_tab(Pid)

==================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_partition.erl#L67 "View Source")

```

-spec retrieve_tab(Pid :: pid()) -> atom() | [ets:tid](https://www.erlang.org/doc/man/ets.html#type-tid)().

```

[Link to this function](#start_link/4 "Link to this function")

start\_link(Tab, PartitionedTablePid, PartitionIndex, Options)

==============================================================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_partition.erl#L55 "View Source")

```

-spec start_link(Tab :: atom() | [ets:tid](https://www.erlang.org/doc/man/ets.html#type-tid)(),

           PartitionedTablePid :: pid(),

           PartitionIndex :: non_neg_integer(),

           Options :: [term()]) ->

              {ok, pid()} | ignore | {error, term()}.

```

[Link to this function](#stop/1 "Link to this function")

stop(Pid)

=========

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_partition.erl#L71 "View Source")

Equivalent to [stop(Server, 5000)](#stop/2).

[Link to this function](#stop/2 "Link to this function")

stop(Pid, Timeout)

==================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_partition.erl#L75 "View Source")

```

-spec stop(Pid :: pid(), Timeout :: timeout()) -> ok.

```

[Link to this function](#tid/2 "Link to this function")

tid(Tab, Partition)

===================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_partition.erl#L79 "View Source")

```

-spec tid(Tab :: [shards:tab](shards.html#t:tab/0)(), Partition :: non_neg_integer()) -> [ets:tid](https://www.erlang.org/doc/man/ets.html#type-tid)().

```

[Link to this function](#tid/3 "Link to this function")

tid(Tab, Key, Meta)

===================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_partition.erl#L83 "View Source")

```

-spec tid(Tab :: [shards:tab](shards.html#t:tab/0)(), Key :: term(), Meta :: [shards\_meta:t](shards_meta.html#t:t/0)()) -> [ets:tid](https://www.erlang.org/doc/man/ets.html#type-tid)().

```





shards\_partition\_sup — shards v1.1.0

 try {

 var settings = JSON.parse(localStorage.getItem('ex\_doc:settings') || '{}');

 if (settings.theme === 'dark' ||

 ((settings.theme === 'system' || settings.theme == null) &&

 window.matchMedia('(prefers-color-scheme: dark)').matches)

 ) {

 document.body.classList.add('dark')

 }

 } catch (error) { }

 

Settings

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_partition_sup.erl#L13 "View Source")

shards\_partition\_sup

(shards v1.1.0)

=============================================================================================================================================================

This supervisor represents a partitioned table, which is composed by a group of ETS tables, each of them owned by `shards_partition`.

This supervisor holds and handles the supervision tree for a partitioned table. Every time a new partioned table is created, a new supervision tree is created to handle its lifecycle, and this module is the main supervisor for that tree.

 

[Link to this section](#summary)

 Summary

==========================================

[Types](#types)

----------------

[opts/0](#t:opts/0)

[Functions](#functions)

------------------------

[init(\_)](#init/1)

[start\_link(Name, Opts)](#start_link/2)

[stop(SupRef)](#stop/1)

Equivalent to [stop(Pid, 5000)](#stop/2).

[stop(SupRef, Timeout)](#stop/2)

[Link to this section](#types)

Types

=====================================

[Link to this type](#t:opts/0 "Link to this type")

opts/0

======

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_partition_sup.erl#L31 "View Source")

```

-type opts() :: #{atom() => term()}.

```

[Link to this section](#functions)

Functions

=============================================

[Link to this function](#init/1 "Link to this function")

init(\_)

========

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_partition_sup.erl#L59 "View Source")

[Link to this function](#start_link/2 "Link to this function")

start\_link(Name, Opts)

=======================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_partition_sup.erl#L41 "View Source")

```

-spec start_link(Name, Opts) -> OnStart

              when

                  Name :: atom(),

                  Opts :: [opts](#t:opts/0)(),

                  OnStart :: {ok, pid()} | ignore | {error, term()}.

```

[Link to this function](#stop/1 "Link to this function")

stop(SupRef)

============

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_partition_sup.erl#L45 "View Source")

Equivalent to [stop(Pid, 5000)](#stop/2).

[Link to this function](#stop/2 "Link to this function")

stop(SupRef, Timeout)

=====================

[View Source](https://github.com/cabol/shards/blob/v1.1.0/src/shards_partition_sup.erl#L51 "View Source")

```

-spec stop(SupRef, Timeout) -> ok when SupRef :: atom() | pid(), Timeout :: timeout().

```





Getting Started — shards v1.1.0

 try {

 var settings = JSON.parse(localStorage.getItem('ex\_doc:settings') || '{}');

 if (settings.theme === 'dark' ||

 ((settings.theme === 'system' || settings.theme == null) &&

 window.matchMedia('(prefers-color-scheme: dark)').matches)

 ) {

 document.body.classList.add('dark')

 }

 } catch (error) { }

 

Settings

[View Source](https://github.com/cabol/shards/blob/v1.1.0/guides/getting-started.md#L1 "View Source")

Getting Started

==================================================================================================================================

[table-of-contents](#table-of-contents)

 Table of Contents

-----------------------------------------------------------

* **[Prelude](#prelude)**

* **[Installation](#installation)**

	+ [Erlang](#erlang)

	+ [Elixir](#elixir)

* **[Creating partitioned tables](#creating-partitioned-tables)**

* **[Inserting entries](#inserting-entries)**

* **[Retrieving entries](#retrieving-entries)**

* **[Making partitioned tables part of an application's supervision tree](#making-partitioned-tables-part-of-an-applications-supervision-tree)**

	+ [Erlang example](#erlang-example)

	+ [Elixir example](#elixir-example)

* **[Advanced topics](#advanced-topics)**

	+ **[Caching the metadata](#caching-the-metadata)**

[prelude](#prelude)

 Prelude

-----------------------------

In this guide, we're going to learn some basics about `shards`, how to create

partitioned tables and how to use them; which is the easiest part, since

it is the same ETS API.

[installation](#installation)

 Installation

--------------------------------------------

### 

[erlang](#erlang)

 Erlang

In your `rebar.config`:

```

{deps, [

 {shards, "1.1.0"}

]}.

```

### 

[elixir](#elixir)

 Elixir

In your `mix.exs`:

```

def deps do

 [{:shards, "~> 1.1"}]

end

```

[creating-partitioned-tables](#creating-partitioned-tables)

 Creating partitioned tables

-----------------------------------------------------------------------------------------

Exactly as ETS, `shards:new/2` function receives 2 arguments, the name of the

table and the options. But in addition to the options given by `ets:new/2`,

`shards` provides the next ones:

* `{partitions, pos_integer()}` - Allows to set the desired number of

partitions. By default, the number of partitions is the total of online

schedulers (`erlang:system_info(schedulers_online)`).

* `{keyslot_fun, shards_meta:keyslot_fun()}` - Function used to compute the

partition where the action will be evaluated based on the key. Defaults to

`erlang:phash2/2`.

* `{parallel, boolean()}` - Specifies whether `shards` should work in parallel

mode or not, for the applicable functions, e.g.: `select`, `match`, etc. By

default is set to `false`.

* `{parallel_timeout, timeout()}` - When `parallel` is set to `true`, it

specifies the max timeout for a parallel execution. Defaults to `infinity`.

Wen a new table is created, the [metadata](https://github.com/cabol/shards/blob/master/src/shards_meta.erl) is created for that

table as well. The purpose of the **metadata** is to store information related

to that table, such as: number of partitions, keyslot function, etc. To learn

more about it, check out [shards\_meta](https://github.com/cabol/shards/blob/master/src/shards_meta.erl).

**Erlang:**

```

% create a named table with 4 shards

> shards:new(tab1, [named\_table, {partitions, 4}]).

tab1

% create another one with default options

> shards:new(tab2, []).

#Ref<0.893853601.1266286595.53859>

```

**Elixir:**

```

# create a named table with 4 shards

iex> :shards.new(:tab1, [:named\_table, partitions: 4])

:tab1

# create another one with default options

iex> :shards.new(:tab2, [])

#Reference<0.1257361217.1909325839.17166>

```

> **NOTE:** You can also start the observer by calling `observer:start()`

> to see how a partitioned table looks like.

> 

> 

[inserting-entries](#inserting-entries)

 Inserting entries

-----------------------------------------------------------

**Erlang:**

```

> shards:insert(tab1, {k1, 1}).

true

> shards:insert(tab1, [{k1, 1}, {k2, 2}]).

true

> shards:insert\_new(tab1, {k3, 3}).

true

> shards:insert\_new(tab1, {k3, 3}).

false

> shards:insert\_new(tab1, [{k3, 3}, {k4, 4}]).

false

```

**Elixir:**

```

iex> :shards.insert(:tab1, k1: 1)

true

iex> :shards.insert(:tab1, k1: 1, k2: 2)

true

iex> :shards.insert\_new(:tab1, k3: 3)

true

iex> :shards.insert\_new(:tab1, k3: 3)

false

iex> :shards.insert\_new(:tab1, k3: 3, k4: 4)

false

```

[retrieving-entries](#retrieving-entries)

 Retrieving entries

--------------------------------------------------------------

**Erlang:**

```

% inserting some objects

> shards:insert(tab1, [{k1, 1}, {k2, 2}, {k3, 3}]).

true

% let's check those objects

> shards:lookup(tab1, k1).

[{k1,1}]

> shards:lookup(tab1, k2).

[{k2,2}]

> shards:lookup(tab1, k3).

[{k3,3}]

> shards:lookup(tab1, k4).

[]

> shards:lookup\_element(tab1, k3, 2).

3

% delete an object and then check

> shards:delete(tab1, k3).

true

> shards:lookup(tab1, k3).

[]

% now let's find all stored objects using select

> MatchSpec = ets:fun2ms(fun({K, V}) -> {K, V} end).

[{{'$1','$2'},[],[{{'$1','$2'}}]}]

> shards:select(tab1, MatchSpec).

[{k2,2},{k1,1}]

```

**Elixir:**

```

iex> :shards.insert(:tab1, k1: 1, k2: 2, k3: 3)

true

iex> :shards.lookup(:tab1, :k1)

[k1: 1]

iex> :shards.lookup(:tab1, :k2)

[k2: 2]

iex> :shards.lookup(:tab1, :k3)

[k3: 3]

iex> :shards.lookup(:tab1, :k4)

[]

iex> :shards.lookup\_element(:tab1, :k3, 2)

3

iex> :shards.delete(:tab1, :k3)

true

iex> :shards.lookup(:tab1, :k3)

[]

iex> ms = :ets.fun2ms(& &1)

[{:"$1", [], [:"$1"]}]

iex> :shards.select(:tab1, ms)

[k2: 2, k1: 1]

```

As you may have noticed using `shards` is extremely easy, it's only matters of

using the same ETS API but with `shards` module.

You can try the rest of the ETS API but using `shards`.

[making-partitioned-tables-part-of-an-application-s-supervision-tree](#making-partitioned-tables-part-of-an-application-s-supervision-tree)

 Making partitioned tables part of an application's supervision tree

-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

There might be some cases we may want to start the tables as part of an

existing supervision tree. To do so, we can create a dynamic supervisor

for taking care of creating/deleting the tables and add the dynamic

supervisor as part of our app supervision tree.

Shards provides the module `shards_group`, which is a dynamic supervisor that

can bee added to an existing application and/or supervision tree. Besides,

`shards_group` brings with the function to create tables making them part of

the dynamic supervisor and also with the function to delete them and remove

them from the dynamic supervisor. But let's see how it works!

### 

[erlang-example](#erlang-example)

 Erlang example

Supposing you have an application `myapp` and the main supervisor `myapp_sup`,

the only piece of configuration is to setup the `shards_group` as a supervisor

within the application's supervision tree, like so:

```

-module(myapp\_sup).

-export([start\_link/1, init/1]).

start\_link() ->

 supervisor:start\_link({name, ?MODULE}, ?MODULE, []).

init(\_) ->

 Children = [

 % Dynamic supervisor with default name shards\_group

 % See shards\_group:child\_spec/1

 shards\_group:child\_spec()

 ],

 {ok, {{one\_for\_one, 10, 10}, Children}}.

```

> The call `shards_group:child_spec()` will return the spec using the default

> name for the dynamic supervisor `shards_group`, but can pass the desired name

> by calling `shards_group:child_spec(desired_name)`.

> 

> 

Once the app is started, you can use `shards_group` to create/delete tables

and `shards` for the rest of the API functions, like so:

```

% create a table as part of the app supervision tree

> shards\_group:new\_table(myapp\_dynamic\_sup, tab1, [named\_table]).

{ok,<0.194.0>,#Ref<0.3052443831.2753691659.260835>}

> shards:insert(tab1, [{a, 1}, {b, 2}]).

true

> shards:lookup\_element(tab1, a, 2).

1

% let's create another table

> {ok, \_Pid, Tab} = shards\_group:new\_table(myapp\_dynamic\_sup, tab2, []).

{ok,<0.195.0>,#Ref<0.3052443831.2753691659.260836>}

> shards:insert(tab2, [{c, 3}, {d, 4}]).

true

> shards:lookup\_element(tab1, c, 2).

3

% you can open the observer to see hoe the tables look like

> observer:start().

ok

% deleting a table

> shards\_group:del\_table(myapp\_dynamic\_sup, tab1).

true

```

### 

[elixir-example](#elixir-example)

 Elixir example

In Elixir is much easier it provides the [`DynamicSupervisor`](https://hexdocs.pm/elixir/DynamicSupervisor.html) module out-of-box,

so we have two options, either use `:shards_group` like before in the Erlang

example, or use [`DynamicSupervisor`](https://hexdocs.pm/elixir/DynamicSupervisor.html) and create a simple module to encapsulate

the logic of creating/deleting tables. Since we already know how `:shards_group`

works in the previous example, let's take the second option.

First of all, let's create the module to encapsulate the logic of creating and

deleting the tables:

```

defmodule MyApp.DynamicShards do

 @moduledoc false

 # creates a table with shards as part of the DynamicSupervisor which at

 # the same time is part of the app supervision tree

 def new(name, opts) do

 {:ok, \_pid, tab} =

 DynamicSupervisor.start\_child(\_\_MODULE\_\_, table\_spec(name, opts))

 tab

 end

 # deletes the table and also removes the table supervisor from the

 # DynamicSupervisor

 def delete(tab) do

 DynamicSupervisor.terminate\_child(\_\_MODULE\_\_, :shards\_meta.tab\_pid(tab))

 end

 # this functions encapsulates the logic of creating the sharded table

 # as child of the DynamicSupervisor

 def start\_table(name, opts) do

 tab = :shards.new(name, opts)

 pid = :shards\_meta.tab\_pid(tab)

 {:ok, pid, tab}

 end

 # DynamicSupervisor child spec

 defp table\_spec(name, opts) do

 %{

 id: name,

 start: {\_\_MODULE\_\_, :start\_table, [name, opts]},

 type: :supervisor

 }

 end

end

```

The final piece of configuration is to setup a [`DynamicSupervisor`](https://hexdocs.pm/elixir/DynamicSupervisor.html) as a

supervisor within the application's supervision tree, which we can do in

`lib/my_app/application.ex`, inside the `start/2` function:

```

def start(\_type, \_args) do

 children = [

 {DynamicSupervisor, strategy: :one\_for\_one, name: MyApp.DynamicShards}

 ]

 ...

```

Now we can use `:shards`:

```

iex> MyApp.DynamicShards.new(:t1, [:named\_table])

:t1

iex> t2 = MyApp.DynamicShards.new(:t2, [])

#Reference<0.2506606486.3592028173.65798>

iex> :shards.insert(:t1, a: 1, b: 2)

true

iex> :shards.insert(t2, c: 3, d: 4)

true

iex> :shards.lookup\_element(:t1, :a, 2)

1

iex> :shards.lookup\_element(t2, :c, 2)

3

# open the observer

iex> :observer.start()

ok

# delete a table

iex> MyApp.DynamicShards.delete(:t1)

:ok

```

[advanced-topics](#advanced-topics)

 Advanced topics

-----------------------------------------------------

[storing-and-retrieving-custom-metadata-entries](#storing-and-retrieving-custom-metadata-entries)

 Storing and retrieving custom metadata entries

--------------------------------------------------------------------------------------------------------------------------------------------------

Since `shards` uses an internal ETS table for the metadata, it also provides

helper functions for storing and retrieving custom metadata entries.

```

> Tab = shards:new(mytab, [named\_table, {partitions, 4}]).

mytab

> shards:put\_meta(Tab, foo, bar).

ok

> shards:get\_meta(Tab, foo).

bar

% Non-existing key

> shards:get\_meta(Tab, foo\_foo).

undefined

% With default

> shards:get\_meta(Tab, foo\_foo, bar\_bar).

bar\_bar

```

**Elixir:**

```

iex> tab = :shards.new(:mytab, [:named\_table, partitions: 4])

:mytab

iex> :shards.put\_meta(tab, "foo", "bar")

:ok

iex> :shards.get\_meta(tab, "foo")

"bar"

# Non-existing key

iex> :shards.get\_meta(tab, "foo foo")

:undefined

# With default

iex> :shards.get\_meta(tab, "foo foo", "bar bar")

"bar bar"

```

### 

[caching-the-metadata](#caching-the-metadata)

 Caching the metadata

Like it is explained in [shards module](https://hexdocs.pm/shards/shards.html),

when a partitioned table is created there is a metadata associated to it, to

resolve the number of partitions and other needed attributes. Hence, every time

a function is executed, `shards` has to resolve the metadata first; but this is

done internally by `shards`. Nevertheless, `shards` allows to pass the metadata

as last argument for most of the functions (check the docs to see what functions

allow it), in case you are able to cache it and use it later for further

operations. This is possible because the metadata is something doesn't change,

so it can be easily cached and avoid `shards` the extra step to retrieve it

from the meta table. But be aware this is just an ETS lookup, so the improvement

is terms of performance may be insignificant, for that reason it is

recommendable to evaluate very carefully each scenario and and see if its really

worth it.

> The overall recommendation is to let `shards` take care of retrieving the

> metadata and everything else, just use the base `shards` API (ETS API).

> 

> 

In case you want to cache the metadata:

**Erlang:**

```

> Tab = shards:new(mytab, [named\_table, {partitions, 4}]).

mytab

> Meta = shards:table\_meta(Tab).

{meta,<0.174.0>,1,4,fun erlang:phash2/2,false,[named\_table]}

```

**Elixir:**

```

iex> tab = :shards.new(:mytab, [:named\_table, partitions: 4])

:mytab

iex> meta = :shards.meta(tab)

{:meta, #PID<0.163.0>, 1, 4, &:erlang.phash2/2, false, [:named\_table]}

```

Then, you can use it for most of the functions (check the docs):

**Erlang:**

```

> shards:insert(Tab, [{a, 1}, {b, 2}], Meta).

true

> shards:lookup(Tab, a, Meta).

[{a,1}]

> shards:lookup\_element(Tab, a, 2, Meta).

1

```

**Elixir:**

```

iex> :shards.insert(tab, [a: 1, b: 2], meta)

true

iex> :shards.lookup(tab, :a, meta)

[a: 1]

iex> :shards.lookup\_element(tab, :a, 2, meta)

1

```

> **NOTE:** See [shards](https://hexdocs.pm/shards/shards.html) docs for more

> information about the functions that support receiving the metadata; most of

> them allow the metadata parameter, but there are few exceptions you should

> know.

> 

> 

[← Previous Page

 

API Reference](api-reference.html)

[Next Page →

 

Shards](readme.html)

