# `Electric.Client.ShapeDefinition`
[🔗](https://github.com/electric-sql/electric/tree/%40core/elixir-client%400.9.4/packages/elixir-client/lib/electric/client/shape_definition.ex#L1)

Struct for defining a shape.

    iex> ShapeDefinition.new("items", where: "something = true")
    {:ok, %ShapeDefinition{table: "items", where: "something = true", replica: :default}}

# `option`

```elixir
@type option() ::
  {:where, nil | binary()}
  | {:columns, nil | [binary()]}
  | {:namespace, nil | binary()}
  | {:params,
     nil
     | %{optional(pos_integer()) => binary() | integer() | float() | boolean()}
     | [binary() | integer() | float() | boolean()]}
  | {:replica, term()}
  | {:parser, {module(), [term()]}}
```

# `options`

```elixir
@type options() :: [option()]
```

# `t`

```elixir
@type t() :: %Electric.Client.ShapeDefinition{
  columns: [String.t(), ...] | nil,
  namespace: String.t() | nil,
  params: term(),
  parser: {atom(), term()},
  replica: term(),
  table: String.t(),
  where: nil | String.t()
}
```

# `matches?`

```elixir
@spec matches?(t(), t()) :: boolean()
```

Tests if two `%ShapeDefinition{}` instances are equal, ignoring the `parser`
setting.

## Example

    iex> {:ok, shape1} = Electric.Client.ShapeDefinition.new("items")
    iex> {:ok, shape2} = Electric.Client.ShapeDefinition.new("items")
    iex> Electric.Client.ShapeDefinition.matches?(shape1, shape2)
    true
    iex> {:ok, shape3} = Electric.Client.ShapeDefinition.new("items", where: "something = 'here'")
    iex> Electric.Client.ShapeDefinition.matches?(shape1, shape3)
    false

# `new`

```elixir
@spec new(String.t() | keyword()) :: {:ok, t()} | {:error, term()}
```

# `new`

```elixir
@spec new(String.t(), options()) :: {:ok, t()} | {:error, term()}
```

Create a `ShapeDefinition` for the given `table_name`.

## Options

* `:where` - Filter the table according to the where clause. The default value is `nil`.

* `:columns` - List of columns to include in the shape. Must include all primary keys. If `nil` this is equivalent to all columns (`SELECT *`) The default value is `nil`.

* `:namespace` - The namespace the table belongs to. If `nil` then Postgres will use whatever schema is the default (usually `public`). The default value is `nil`.

* `:params` - Values of positional parameters in the where clause. These will substitute `$i` placeholder in the where clause. The default value is `nil`.

* `:replica` - Modifies the data sent in update and delete change messages.

  When set to `:full` the entire row will be sent for updates and deletes,
  not just the changed columns.

  The default value is `:default`.

* `:parser` - A `{module, args}` tuple specifying the `Electric.Client.ValueMapper`
  implementation to use for mapping values from the sync stream into Elixir
  terms. The default value is `{Electric.Client.ValueMapper, []}`.

# `new!`

# `new!`

```elixir
@spec new!(String.t(), options()) :: t() | no_return()
```

# `public_keys`

# `url_table_name`

```elixir
@spec url_table_name(t()) :: String.t()
```

Return a string representation of the shape's table, quoted for use in API URLs.

    iex> ShapeDefinition.url_table_name(ShapeDefinition.new!("my_table"))
    "my_table"

    iex> ShapeDefinition.url_table_name(ShapeDefinition.new!("my_table", namespace: "my_app"))
    "my_app.my_table"

    iex> ShapeDefinition.url_table_name(ShapeDefinition.new!("my table", namespace: "my app"))
    ~s["my app"."my table"]

# `url_table_name`

---

*Consult [api-reference.md](api-reference.md) for complete listing*