# Extract Declarations

An extract declaration file allows you to define what
sobjects and fields to extract from an org. An extract
declaration can be specified directly as an option to
the `capture_sample_data` task, but most often you
will just edit the one attached to the sample dataset you
are working on, such as `datasets/default/default.extract.yml`
or `datasets/qa/qa.extract.yml`. This file is automatically
generated by `capture_sample_data` or by Metecho.

An extract declaration looks like this:

```yaml
extract:
    Opportunity:
        fields:
            - Name
            - ContactId
            - AccountId
```

This extracts opportunities explicitly, but also Accounts and Contacts
implicitly, because `ContactId` and `AccountId` rely on them. In addition
to the named fields, it extracts required fields of Opportunity, Contact
and Account.

That declaration is therefore the same as:

```yaml
# This will download the Salesforce-y trinity
# of Accounts, Contacts and Opportunities
extract:
    Opportunity:
        fields:
            - Name
            - ContactId
            - AccountId
            - FIELDS(REQUIRED)
    Account:
        fields:
            - FIELDS(REQUIRED)
    Contact:
        fields:
            - FIELDS(REQUIRED)
```

The `FIELDS` declarations can be `REQUIRED`, `STANDARD`, `CUSTOM` or `ALL`.
In any case, you will alway get required fields.

So for example, you can extract all standard fields of `Opportunity`,
all custom fields (plus required fields) of `Account` and all (createable) fields
of `Contact` in general.

```yaml
extract:
    Opportunity:
        fields:
            - FIELDS(STANDARD)
    Account:
        fields:
            - FIELDS(CUSTOM)
    Contact:
        fields:
            - FIELDS(ALL)
```

As a side effect, this will pull down many other objects referenced
by fields that were referred to. For example ... XXX

If you wanted to pull out many objects from an org, it might be easier
to pull them out with with wildcards. There are wildcards for
"all objects" (`OBJECTS(ALL)`), "all standard objects" (`OBJECTS(STANDARD)`),
and "all custom objects" (`OBJECTS(CUSTOM)`). For example, to pull out
all Account fields, all Standard Fields on Custom objects and all Custom
fields on Standard objects (plus required fields) you would do this:

```yaml
extract:
    Account:
        fields:
            - FIELDS(ALL)
    OBJECTS(CUSTOM):
        fields:
            - FIELDS(STANDARD)
    OBJECTS(ALL):
        fields:
            - FIELDS(CUSTOM)
```

If you want just a subset of records from an sobject, you can use a
`where` clause.

```yaml
extract:
    Account:
        fields:
            - FIELDS(ALL)
        where: FirstName='Buster'
```

# <<<<<<< Updated upstream

Be careful with this feature: If this object has a child object
that depends on it (e.g. `Contact` through `AccountId`) then child
records may not link properly to their parent records.

> > > > > > > Stashed changes
> > > > > > > If a particular sobject needs to explicitly be extracted with either the
> > > > > > > `bulk` or `rest` APIs, you can control that as well:

```yaml
extract:
    Account:
        fields:
            - FIELDS(ALL)
        api: REST
```