# Alias

An `Alias` is a proxy to another field, potentially nested, within the same document.

Utilizing an `Alias` allows class-level querying and instance-level read access, write access under most conditions, as well as optional deprecation warning generation.

#### Import

`from marrow.mongo.field import Alias`

#### Inherits

`marrow.schema:`**`Attribute`**

#### Added

`>=1.1.0` [Oranir](https://github.com/marrow/mongo/releases/tag/1.1.0)

## Attributes

This pseudo-field **does not** inherit other field attributes.

#### `path`

A string reference to another field in the same containing class. See the [Usage](/reference/fields/alias.md#usage) section below for the structure of these references.

Required

#### `deprecate`

Used to determine if access should issue `DeprecationWarning` messages. If truthy, a warning will be raised, and if non-boolean the string value will be included in the message.

Default`False`

Added`>=1.1.2`

## Usage

Instantiate and assign an instance of this class during construction of a new `Document` subclass, passing the attributes in as positional (in the order seen above) or keyword arguments. This pseudo-field utilizes the Marrow Package [`traverse`](https://github.com/marrow/package#4-resolving-object-references) utility to allow it to resolve a wide variety of attributes.

References to other fields may be:

* The string name of a sibling attribute.

  Example`'id'`
* The path to a descendant attribute of a sibling.

  Example`'address.city'`
* Or involving numeric array indexes.

  Example`'some_array.0'`
* Or involving dictionary key references.

  Example`'locale.en'`

Paths are strings comprised of dot-separated attribute names. The search beings at the containing document, consuming path elements as we go. Each path element is first attempted as an attribute and, failing that, will attempt dictionary access. If the path element is numeric, it will be utilized as an array index.

Accessing an `Alias` at the class level will resolve a Queryable for the target field, allowing filter document construction through comparison utilizing the `alias` name itself. On an instance access will retrieve or assign the value of the target field.

## Examples

### Sibling Reference

As it might not be natural to refer to the user's username everywhere as `id`, especially if dereferenced from a variable, you can use an `Alias` to provide a more contextual name for the identifier.

```python
class User(Document):
    id = String('_id')
    username = Alias('id')


User.find_many(username__startswith="a")
```

### Descendant Attribute of a Sibling

There are situations where elevating an embedded value can be useful to, for example, shorten frequent queries or variable references in templates.

```python
class Package(Document):
    class Address(Document):
        city = String()
        ...

    address = Embed(Address, assign=True)
    city = Alias('address.city')
```

### Numeric Array Index Reference

If you're savvy and always insert the most recent message at the beginning of the unread messages array, you can easily and semantically access the latest message using an `Alias`.

```python
class Conversation(Document):
    class Message(Document):
        id = ObjectId('_id')
        sender = Field()
        message = Field()

    messages = Array(Embed(Message), assign=True)
    latest = Alias('messages.0')
```

### Legacy Alternative Names / Deprecation

Data modelling requirements change over time and there can be a lot of code referencing a given document attribute. Help identify where that access is coming from by marking old, deprecated attributes using `Alias` with an appropriate message.

Added`>=1.1.2`

```python
class User(Document):
    id = String('_id')
    username = Alias('id',
        deprecate="Username is now primary key.")
```

## See Also

* [`traverse`](https://github.com/marrow/package#4-resolving-object-references)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mongo.webcore.io/reference/fields/alias.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.