Export Import

What can I do with export/import?

  1. Export/import any data to/from GoogleSheets/Excel in Editor (during game development)
  2. Update database data on players devices at runtime with LiveUpdate plugin
  3. Currently there is no way to write to GoogleSheets at runtime from players devices (Why not?)
  4. Backup/restore database in json format in Editor

Description

You can edit database data in external tools, such as Excel/Open Office/Libre Office or Google Sheets.

BG Database provide export/import functions to xls files, Google Sheets and json (backup only).

Full import/export works in Editor only, but you can update database data on players devices from GoogleSheets with LiveUpdate addon. No way to update GoogleSheets data from players devices yet.

Use json export/import to create full database backup.

This article describes common procedure and ideas, common for both Excel and Google Sheets. You can find provider' specific instruction here: for Excel/Open Office, for Google Sheets

General idea

Here is the illustration about how BGDatabase data is mapped to spreadsheets.

Using merge settings

You have full control over which data you want to synchronize: you can add, delete, update and you can chose which fields you wish to update.

Here is how it works: Every synchronization has a source and a destination. If you are exporting data from BDDatabase to, let's say, Excel file- the source is BGDatabase and a destination- is Excel file. Here is how data is classified during syncing:

So, there are 3 types of rows during syncing:

  1. Matching rows : they exists in the Source and in the Destination. Can be updated and you can chose which fields to update.
  2. Missing rows : they exists only in the Source. Can be added to Destination.
  3. Orphaned rows : they exists only in the Destination. Can be removed from Destination.

Let's look at merge settings and find out how we can define actions to take during syncing

Row-level control for merge settings

Merge settings let you configure which table/fields you want to add/delete/update, but it does not give you the opportunity to define which rows you want to add/delete/update

For row-level control, you can implement C# controller class, which can cancel any operation if some condition is met. This is how:

  • Create your own C# class with unique name, set this class name to "Controller Type" field of merge settings (using the full name with namespace).
  • Implement any number of interfaces (namespace is BansheeGz.BGDatabase, interfaces defined inside class BGMergeSettingsEntity), listed below to receive callback method invocations. Return true from this methods to cancel operation
Interface type method(s) to implement description
IMergeReceiver public bool OnBeforeMerge(BGRepo from, BGRepo to)
public void OnAfterMerge(BGRepo @from, BGRepo to)
Callbacks to be called before after merging. Return true from OnBeforeMerge to cancel merging
IRemoveOrphanedReceiver public bool OnBeforeDelete(BGEntity toEntity) Callbacks to be called before deleting the row. Return true to cancel removal.
IAddMissingReceiver public bool OnBeforeAdd(BGEntity fromEntity) Callbacks to be called before adding the row. Return true to cancel adding.
IUpdateMatchingReceiver public bool OnBeforeUpdate(BGEntity @from, BGEntity to) Callbacks to be called before updating the row. Return true to cancel updating.
IUpdateMatchingFieldReceiver public bool OnBeforeFieldUpdate(BGField fromField, BGField toField, BGEntity @from, BGEntity to) Callbacks to be called before updating the row' field. The same as IUpdateMatchingReceiver, but it's called on per field basis. IUpdateMatchingReceiver is called before this callback, and if IUpdateMatchingReceiver return true, this callback will never be invoked (cause updating entity will be cancelled by IUpdateMatchingReceiver)

You can find an example of such controller class on Save/Load addon page.

Default field value string format

We use Acute (Back quote) symbol ` to separate tokens of single value, for example Vector3.zero is 0`0`0

We use Vertical bar (Pipe) symbol | to separate values of the list, for example List<bool> is 0|1|0

Custom field value string format

Most of the fields support custom string format (except for Unity assets and relations). You can create your own class, implementing BGStringFormatter<T> interface (T is a field value type) and assign it under "M" menu as a custom string value formatter

Adding rows in external tools

Each row has it's own id- 22 symbols string. It's computer-generated value, based on Guid generation.

While creating rows in external tool, you can leave it blank, and it will be updated during importing procedure (make sure you toggled "Update Ids on Import" on)

Creating database backup in json format

Exporting data to json allows you to create a full database backup in human readable form as json file. With json you can not chose which data you want to be exported/imported, full data including database structure will be included.

You can use this backup later to fully restore the database (including structure)

Why you do not provide an option to update GoogleSheets data from player devices?

We believe giving direct write GoogleSheets access to player devices does not make much sense, due to the following reasons:

  1. Durability problem: this is the main reason- there is no way to make sure some change will not erase previous change. Let's say you want to store the number of times your app was launched. So you read cell value, you increase it by 1 and you write it back. But if 10 players launch your game simultaneously, they all read initial zero value from GoogleSheets, increase it by one and write it back, so the final value will be 1, not 10. This problem apply to any shared data.
  2. Security problem: giving write access means giving credentials to change data, and there is no way to make sure these credentials will not be hacked
  3. Performance problem: GoogleSheets is not fast enough to be used as online database for big amount of users. Many tasks will require to read data first before updating, and it can take a lot of time. Also there is 2 million cells max restriction.

All this problems can be solved with a proxy server, but it means there is no need for direct access to GoogleSheets. If you are still looking for a way to write data to GoogleSheets from players devices GoogleSheets dotnet API library v3 is probably the best starting point. There is also newer and better v4 version available (targeting Net 4.x), but we are not sure if it's compatible with Android and IOS devices.

What's next?

Read product specific guides next
  1. Excel/Open Office
  2. Google Sheets