> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parable.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Handles

> Understand how Pieces and Perception bindings are named in code and SQL, and what a rename does.

## Sources

Docs: [Panes](/ponder/parables/pieces/panes), [Perceptions](/ponder/parables/pieces/perceptions), and [Plots](/ponder/parables/pieces/plots)

Web App: Rename a Pane or Plot in **Pieces**; open a Pane's code afterwards to see the new handle already in place.

## Story

Every named Page, Package, Pane, and Plot in a Parable has a handle: a camelCase name, unique within the Parable, that
code and SQL use. Underneath, every Piece and slot also has a permanent
identifier that never changes, and that identifier is what the Parable
actually stores, including inside Pane code. Perceptions accept handles for references and save the stable identifier, so
renaming a Piece preserves its references.

## Where handles appear in code

The editor shows and accepts handles in exactly these places, and Parable
translates them to identifiers when it saves and back to handles when it
reads:

* the import specifier `@parable/<parable>/<pane>`;
* the string that is the first argument of `preferences.get('...')` and
  `plots.run('...')`;
* the `handle` inside `preferences.set({ handle: '...', value })`; and
* the bracket access `plots['...']` and `panes['...']`.

Always write those positions as string literals. Dotted access such as
`plots.salesQuery` is not part of the generated module, and a handle built at
run time cannot be translated.

A handle that the Pane does not declare is refused at save. The refusal names
the handle, lists the handles the Pane may use, and, when the same save renamed
that handle, names the rename.

## In SQL

Plot SQL is never rewritten. The `workspace.preferences` relation a Plot reads
carries the handle beside the slot's identifier, so
`WHERE handle = 'salesQuery'` selects by the current handle. If that handle
changes, update a literal SQL condition that still names the old handle.

## What a rename does

A rename is an identity edit. It touches no code and no stored value: values
set at Person and Workspace scope stay attached to the slot's identifier, and
the editor rewrites any open draft that still used the old handle before its
next save. Teammates editing the same Parable see the new handle in their
drafts without losing their changes.

A Piece handle must be unique across the Parable. Perception binding names
are local to their own `panes` or `plots` map; they can differ from the
referenced Piece's handle and do not claim a global Piece handle.

## Reference

Generated Workspace API reference for this Piece:

* [Rename a Parable or change how it is labelled](/protocols/reference/web-api/parable-authoring-set-workspace-parable-identity)
* [Read a Parable's contents](/protocols/reference/web-api/parable-authoring-workspace-parable-primary-package)
* [Read one directory entry](/protocols/reference/web-api/parable-directory-workspace-parable-directory-entry)