Fixtures

Fixtures allow you to loaded flat file data in the form of json or csv into the system at the application starts. Each time the application starts, AMSDAL checks if there is any new data and can either add or update it if the fixture has changed.

Basic usage

Fixtures can be in the following formats:

• JSON
• CSV

To add fixtures, include a fixtures folder inside the class folder and then add a flat file data which will be automatically ingested the next time you start your application.

└── 📁 models
    └── 📁 my_model
        ├── 📁 hooks
        ├── 📄 model.json
        └── 📁 fixtures
            ├── 📄 fixture_example.csv
            └── 📄 fixture_example.json

A fixture itself should have an _external_id and any other data that you would like to ingest.

An _external_id may be referenced by other fixtures and is also used to check if an object needs to be created/modified and must be unique. The _external_id must be unique among all fixtures and all models, because it is used to link fixture and objects.

Note

After deletion of a fixture, the object will not be deleted from the database. You will need to delete it manually.

Example

In this example, the Location model has two fields:

• name: string
• parent: Location
• tags: list[string]

[
    {
        "_external_id": "parent_location",
        "name": "Parent Location",
        "parent": null,
        "tags": [
            "tag1",
            "tag2"
        ]
    },
    {
        "_external_id": "child_location",
        "name": "Child Location",
        "parent": "parent_location"
    },
]

Here, `_external_id`` is used to specify other fixture objects, and create references between them.

Named fixtures

You can also specify a particular class of fixtures and place the file in any fixtures folder for any class, by placing object data in the JSON file instead of a list, where the key is the name of the target class:

{
    "Location": [
        {
            "_external_id": "parent_location",
            "name": "Parent Location",
            "parent": null,
            "tags": [
                "tag1",
                "tag2"
            ]
        },
        {
            "_external_id": "child_location",
            "name": "Child Location",
            "parent": "parent_location"
        }
    ],
    "Person": [
        {
            "_external_id": "john_doe",
            "first_name": "John",
            "last_name": "Doe",
            "location": "parent_location"
        }
    ]
}

CSV file format

Use headers as field names

Here is the same data from above in table format:

_external_id	name	parent	tags
parent_location	Parent Location		tag1,tag2
child_location	Child Location	parent_location

Which can be represented in CSV format:

_external_id,name,parent,tags
parent_location,Parent Location,,"tag1,tag2"
child_location,Child Location,parent_location,

Fixtures with File type

AMSDAL handles a special case for fixtures with the built-in File property type.

Simply create save your file data inside of fixtres/files

Then, from within another fixture, the file can be referenced by its path:

[ModelName]/[FileName]

File type example

For example, we have a model Country with a field icon of type File. We have a file us.png in the models/country/fixtures/files folder.

Then, in the fixtures, we can specify the path to the file in the following format:

[
  {
    "_external_id": "us",
    "name": "United States",
    "code": "US",
    "icon": "Country/us.png"
  }
]

The same will work for CSV format. Also, it will work if your model has a field of type list[File] and you specify a list of files in the fixtures.

For example:

[
  {
    "_external_id": "7fe17f0a-2c63-4076-b0fb-0a75022c489f",
    "name": "Freehand Los Angeles",
    "type": "Hotel",
    "address": "416 W 8th St",
    "free_parking": true,
    "free_wifi": true,
    "photos": [
      "Property/1.jpeg",
      "Property/2.jpeg",
      "Property/3.jpeg"
    ]
  }
]

Ordering

By default, there is not guarantee in which order the fixtures will be loaded. If you need to load fixtures in a specific order, you can use the _order key in the fixture file.

{
    "Location": [
        {
            "_external_id": "parent_location",
            "_order": 1,
            "name": "Parent Location",
            "parent": null
        },
        {
            "_external_id": "child_location",
            "_order": 2,
            "name": "Child Location",
            "parent": "parent_location"
        }
    ],
    "Person": [
        {
            "_external_id": "john_doe",
            "_order": 3,
            "first_name": "John",
            "last_name": "Doe",
            "location": "child_location"
        }
    ]
}

You can use any numeric value (integer or float) for the _order key. The fixtures will be loaded in ascending order of the _order key. The default value is 0, so you can also use negative values to load fixtures before the fixtures without _order key.

{
    "Location": [
        {
            "_external_id": "parent_location",
            "_order": -1,
            "name": "Parent Location",
            "parent": null
        },
        {
            "_external_id": "child_location",
            "_order": -0.5,
            "name": "Child Location",
            "parent": "parent_location"
        }
    ],
    "Person": [
        {
            "_external_id": "john_doe",
            "first_name": "John",
            "last_name": "Doe",
            "location": "child_location"
        }
    ]
}