The original version of this document is located at https://docs.qfield.org/get-started/tutorials/tips-tricks-qfc

Tips and Tricks for your QGIS project

This page will give you an overview of all the tips and tricks you can apply to your project and general workflow to minimize synchronization errors, work efficiently and save storage.

Project Configuration Best Practices

To ensure a smooth synchronization process between QGIS, QField and QFieldCloud, follow these recommendations.

1. Centralized Data Storage - Add all data in the same folder as your .qgs project file

Before uploading your project, ensure all relevant data sources (GeoPackages, rasters, etc.) are located in the same directory as your project file (.qgs/.qgz)
or in a subdirectory (e.g., ./data, ./assets).
If files are spread across different drives or folders on your computer, QFieldSync and QFieldCloud may fail to package them correctly for the mobile device.

2. Managing Unique IDs - Add a unique ID to your layers

When multiple users collect data offline simultaneously, standard auto-incrementing IDs (1, 2, 3…) will result in conflict errors when applying the deltas changes data on QFieldCloud.

• For Relations: Create a specific text field (e.g., survey_uuid) and use uuid() or uuid('WithoutBraces') as the default value.
  Use this field for all foreign keys and for primary key if the layer is from PostgreSQL/PostGIS.
• For the fid (Feature ID): If you are working with GeoPackages, you can reduce conflicts on the internal fid integer column
  by setting the “Default Value” to the expression epoch(now()).
  This generates a unique integer based on the current timestamp.

3. Relative Paths - Ensure that all attachment paths are relative

Absolute paths (e.g., C:\Users\{username}\Downloads\photo_001.jpg) will break when the project is transferred to a mobile device (Android/iOS),
as the file system structure is different.

4. Stable Layer References in Expressions - Use the Layer Name in expressions, not the Layer ID

When writing expressions (for example, inside aggregate() or relation_aggregate()) functions,
QGIS allows you to reference layers by their internal ID (e.g., places_2348274...) or their Name (e.g., Places).
Always use the Layer Name (e.g., Places).

Why?
The internal Layer ID changes if you remove and re-add a layer or internally in QFieldCloud when a packaging job is triggered could change,
which breaks your expressions.
The Layer Name remains stable as long as you do not rename it in the layer tree.

5. Preferred File Formats - Convert your layers to GeoPackage

QField and QFieldCloud are optimized for the GeoPackage (.gpkg) format.
While QField and QFieldCloud support others formats like Shapefiles (.shp), GeoJSON, and KML, etc., is strongly recommend converting these layers to GeoPackage before starting your project.

How to Convert to GeoPackage?

6. Modular File Structure - Store one layer per GeoPackage

QFieldCloud manages versions and backups at the file level. Every time changes are synchronized, a backup of the modified file is created.

• The Risk: If you store multiple layers in a single GeoPackage (e.g., survey_data.gpkg containing Trees, Roads, and Buildings), restoring a backup to fix an error in the Trees layer will also roll back valid work done on Roads and Buildings during that same period.
• The Solution: Save each layer in its own separate GeoPackage (e.g., trees.gpkg, roads.gpkg).
  This allows you to restore a previous version of one specific layer without losing data in others.

Common Configuration Errors

If you are experiencing synchronization issues, check for these common configuration errors:

Download attachments only on demand

In the QFieldCloud settings you can set your attachments to be only downloaded on demand.
This is particularly useful when you work with an abundance of photos and do not need all your attachments at once.

Restriction of Project Files

If you work in field operations which involves a lot of users, it may be useful to restrict the QGIS project file to prevent all users with editor rights to download the project and make changes to the configuration.
To prevent any modification to the core QGIS project file, the project administrator can restrict the access to these files.
This can be achieved under the settings section in QFieldCloud.

Once set, only administrators and managers will be able to push changes to the files listed above.
Other project collaborators can still upload and modify other project files, such as data in GeoPackages, but they cannot alter the main project file or its core components.

Restricted Files

When enabled, the following files can only be modified or uploaded by a user with an “admin” or “manager” role for the project:

• The primary QGIS project file (e.g., my_project.qgz).
• The attachments zip archive associated with the project (e.g., my_project_attachments.zip).
• QGIS auxiliary data files that store information like label positions (e.g., my_project.qgd).
• QField style files (.qml) that share the same name as the project file.

Saving storage

Deleting old file versions

You can reduce the number of versions you want to keep of any given file to reduce the amount of storage needed by accounts.
One can manually delete file versions from the project’s File section.
Each file and version can be linked to a specific QFieldCloud user who uploaded it.

Set maximum pixel size of attachment

If you want to further save space and you are working with attachments, you can reduce the pixel size.
This will lead to lower image quality but take less storage on QFieldCloud.
You can direct to the How-To of the Attachment Widget to see the step-by-step instructions.

Automating file deletion with QFieldCloud SDK

If you accumulate many attachments (such as high-resolution photos) during fieldwork
and want to free up space automatically without manually deleting them from the web interface, you can utilize the QFieldCloud SDK.

By setting up a script or a cron job using the QFieldCloud SDK, you can periodically purge specific file types (e.g., .jpg or .mp4) to keep your storage usage low.

For full details and code snippets, see the QFieldCloud SDK Documentation.

To routinely free up storage quota on QFieldCloud, you can delete unnecessary files, such as heavy .jpg attachments using glob patterns.

=== “:material-language-python: Python”

```python
client.delete_files(
    project_id="123e4567-e89b-12d3-a456-426614174000",
    glob_patterns=["*.csv", "*.jpg"],
    throw_on_error=True
)
```

=== “:material-bash: Bash”

```bash
qfieldcloud-cli delete-files '123e4567-e89b-12d3-a456-426614174000' '*.jpg'
```

=== “:material-powershell: PowerShell”

```powershell
qfieldcloud-cli delete-files "123e4567-e89b-12d3-a456-426614174000" "*.jpg"
```