Model Imports

In this section, we’ll learn how to import your NimbusDB models from various file formats. We’ll use this items model as an example:

GML

var schema = {
    id: {
        type: NIMBUSDB_DATA_TYPE.INTEGER,
        const: NIMBUSDB_CONSTRAINT.PRIMARY_KEY
    },
    name: NIMBUSDB_DATA_TYPE.STRING,
    price: {
        type: NIMBUSDB_DATA_TYPE.NUMBER,
        validator: function(data, value) {
            return value >= 0;
        },
        default_value: 0
    },
    is_locked: {
        type: NIMBUSDB_DATA_TYPE.BOOLEAN,
        const: NIMBUSDB_CONSTRAINT.OPTIONAL,
        default_value: false
    }
};

// empty model
items = new NimbusDBModel(id, "items", schema);

Importing Model Data

Use the import() method to import your model data from a file. If you don’t specify the file extension, NimbusDB will automatically detect the file format based on the file name.

GML

// (1) auto-detect the file format
items.import("items.csv");      // will be imported as CSV
items.import("items.json");     // will be imported as JSON

// (2) specify the file format/extension
items.import("items.csv", {
    type: NIMBUSDB_FILE.CSV     // or `extension: NIMBUSDB_FILE.CSV`
});

// (3) use the game path as the root directory
items.import("~/items.csv", {       // the path will be resolved to "working_directory/items.csv"
    // options for the import...     // `working_directory` is your game path
});

// (4) file extension obfuscation
// this allows you to import files to certain formats that already obfuscated
items.import("items.mydat", {       // a `.mydat` custom file extension
    type: NIMBUSDB_FILE.JSON        // but the content will still be a JSON
});

CSV Import

You can import CSV files using the import() method or the dedicated import_csv() method.

GML

// (1) basic usage
items.import("items.csv");          // using auto-detect file format

items.import("items.someext", {     // specify the file format/extension
    type: NIMBUSDB_FILE.CSV
});

items.import_csv("items.csv");      // using the csv import method

// (2) import options
// all options are usable for both `import()` and `import_csv()`

// (2.1) headers/columns order
items.import_csv("items.csv", {
    headers: ["id", "name", "price"]    // specify the column order
});

JSON Import

You can import JSON files using the import() method or the dedicated import_json() method.

GML

// (1) basic usage
items.import("items.json");         // using auto-detect file format

items.import("items.someext", {     // specify the file format/extension
    type: NIMBUSDB_FILE.JSON
});

items.import_json("items.json");    // using the json import method

JSONL Import

You can import JSONL files using the import() method.

GML

// (1) basic usage
items.import("items.jsonl");        // using auto-detect file format

items.import("items.someext", {     // specify the file format/extension
    type: NIMBUSDB_FILE.JSONL
});

// (2) import options
// (2.1) customizing the start line
items.import("items.jsonl", {
    start_line: 3                   // start importing from the 3rd data
});

// (2.2) customizing the line count
items.import("items.jsonl", {
    line_count: 2                   // import only 2 data, starts from the first data
});

items.import("items.jsonl", {
    start_line: 3,                  // start importing from the 3rd data
    line_count: 2                   // and import only 2 data
});

NDBIN Import Experimental

You can import NDBIN files using the import() method or the dedicated import_ndbin() method.

GML

Any Non-Async Event

// (1) basic usage
items.import("items.ndbin");          // using auto-detect file format

items.import("items.someext", {       // specify the file format/extension
    type: NIMBUSDB_FILE.NDBIN
});

items.import_ndbin("items.ndbin");    // using the ndbin import method

// (2) import options
// all options are usable for both `import()` and `import_ndbin()`

// (2.1) cherry-pick the column(s) for each data
items.import_ndbin("items.ndbin", {
    columns: ["name", "price"]          // only import the "name" and "price" columns
});

// (2.2) only import the data
items.import_ndbin("items.ndbin", {
    data_only: true                     // only import the data, without importing the model definition
});

// (2.3) import asynchronously
// you must store the returned object in an instance variable
items_import = items.import_ndbin("items.ndbin", {
    async: true
});
// from this line, there's no guarantee that the import is finished

Async - Save/Load

items.import(items_import);     // `items` is the model instance to import

Custom Import

You can also implement your own custom import logic by providing a reader callback function to the import() method.

GML

var reader_fn = function(model, data, temp) {
    // write your own logic here
    // `model` is the model instance
    // `data` is the original data in the model (array of structs)
    // `temp` is the temporary data (struct)

    // let's try to import data 1 and 2
    ini_open("items.ini");

    items.name = ini_read_string("model", "name", "");

    var curr_data = [];
    for (var i = 0; i < 2; i++) {
        array_push(curr_data, {
            name: ini_read_string($"data{i + 1}", "name", ""),
            price: ini_read_real($"data{i + 1}", "price", 0),
            is_locked: ini_read_real($"data{i + 1}", "is_locked", false)
        });
    }

    items.migrate(NIMBUSDB_MIGRATION.ARRAY_OF_STRUCT, curr_data, {
        mode: "replace"
    });

    ini_close();

    return true;
}

items.import(reader_fn);

---

References

Model.import()

Imports model data from a file, raw string, async result, or custom reader.

Overload 1

Signature

model.d.ts

class NimbusDBModel {
    // ... other methods and properties ...
    static import(
        _path: string,
        _options?: NimbusDBImportOptions
    ): NimbusDBImportResult;
}

Parameters

_path

• Type: string
• The file path to read from.

_options

• Type: NimbusDBImportOptions
• Default: undefined
• Optional configuration for the operation.

Returns

• Type: NimbusDBImportResult
• The import result metadata.

Overload 2

Signature

model.d.ts

class NimbusDBModel {
    // ... other methods and properties ...
    static import(
        _raw_body: string,
        _options?: NimbusDBImportOptions
    ): NimbusDBImportResult;
}

Parameters

_raw_body

• Type: string
• The raw file content to import.

_options

• Type: NimbusDBImportOptions
• Default: undefined
• Optional configuration for the operation.

Returns

• Type: NimbusDBImportResult
• The import result metadata.

Overload 3

Signature

model.d.ts

class NimbusDBModel {
    // ... other methods and properties ...
    static import(
        _resolve_async: NimbusDBImportResult
    ): NimbusDBImportResult;
}

Parameters

_resolve_async

• Type: NimbusDBImportResult
• The asynchronous import result to resolve.

Returns

• Type: NimbusDBImportResult
• The import result metadata.

Overload 4

Signature

model.d.ts

class NimbusDBModel {
    // ... other methods and properties ...
    static import(
        _reader_fn: (model: NimbusDBModel, data: NimbusDBData[], temp: Struct) => boolean | void
    ): NimbusDBImportResult;
}

Parameters

_reader_fn

• Type: (model: NimbusDBModel, data: NimbusDBData[], temp: Struct) => boolean | void
  • Parameters:
    • model: The model instance.
    • data: The data to import.
    • temp: The temporary data.
  • Returns:
    • true when the operation succeeds, otherwise false, or not returning anything.
• The custom reader callback used during import.

Returns

• Type: NimbusDBImportResult
• The import result metadata.

Model.import_csv()

Imports model data from a CSV file.

Signature

model.d.ts

class NimbusDBModel {
    // ... other methods and properties ...
    static import_csv(
        _path: string,
        _options?: NimbusDBImportOptions
    ): NimbusDBImportResult;
}

Parameters

_path

• Type: string
• The file path to read from.

_options

• Type: NimbusDBImportOptions
• Default: undefined
• Optional configuration for the operation.

Returns

• Type: NimbusDBImportResult
• The import result metadata.

Model.import_json()

Imports model data from a JSON file.

Signature

model.d.ts

class NimbusDBModel {
    // ... other methods and properties ...
    static import_json(
        _path: string,
        _options?: NimbusDBImportOptions
    ): NimbusDBImportResult;
}

Parameters

_path

• Type: string
• The file path to read from.

_options

• Type: NimbusDBImportOptions
• Default: undefined
• Optional configuration for the operation.

Returns

• Type: NimbusDBImportResult
• The import result metadata.

Model.import_ndbin()

Imports model data from an NDBIN file.

Signature

model.d.ts

class NimbusDBModel {
    // ... other methods and properties ...
    static import_ndbin(
        _path: string,
        _options?: NimbusDBImportOptions
    ): NimbusDBImportResult;
}

Parameters

_path

• Type: string
• The file path to read from.

_options

• Type: NimbusDBImportOptions
• Default: undefined
• Optional configuration for the operation.

Returns

• Type: NimbusDBImportResult
• The import result metadata.

NimbusDBImportOptions

An optional configuration object for the NimbusDBModel.import() method.

io.d.ts

type NimbusDBImportOptions = Partial<{
    from_string: boolean;                // whether the first parameter is a raw body string (default = false)
    mode: "append" | "replace";          // append = append to existing data (upsert on primary key, default), replace = clear existing data and import
    no_debug: boolean;                   // don't output warning and success debug messages (default = false)
    type: NIMBUSDB_FILE                  // override import type, default = AUTO
}> & (
    | NimbusDBImportCsvOptions
    | NimbusDBImportJsonOptions
    | NimbusDBImportJsonlOptions
    | NimbusDBImportNdbinOptions
) & NimbusDBUpsertOptions;

NimbusDBImportCsvOptions

An optional configuration object for the NimbusDBModel.import_csv() method.

io.d.ts

type NimbusDBImportCsvOptions = Partial<{
    headers: boolean | string[]          // use first line in .csv as header, default = true. string[] = false, and override it with provided array
    columns: boolean | string[]          // alias for `headers`
}>;

NimbusDBImportJsonOptions

An optional configuration object for the NimbusDBModel.import_json() method.

io.d.ts

type NimbusDBImportJsonOptions = Partial<{

}>;

NimbusDBImportJsonlOptions

An optional configuration object for the NimbusDBModel.import_jsonl() method.

io.d.ts

type NimbusDBImportJsonlOptions = Partial<{
    line_count: int;                     // length of line to import (default = 0, total line in the file)
    start_line: int;                     // start line for importing (default = 1)
    line_offset: int;                    // alias for `start_line`
}>;

NimbusDBImportNdbinOptions

An optional configuration object for the NimbusDBModel.import_ndbin() method.

io.d.ts

type NimbusDBImportNdbinOptions = Partial<{
    async: boolean;                      // import asynchronously (default = true)
    columns: string | string[];          // pick certain column(s) for each data only (default = undefined, get all columns)
    data_only: boolean;                  // only import the data (default = false)
    size: int;                           // size of the file in bytes (default = undefined, total size of the file)
}>;

NimbusDBImportResult

The import result metadata.

io.d.ts

type NimbusDBImportResult = {
    deserialized: boolean;
    path: string;
    success: boolean;
    async_id: AsyncID | undefined;
    buffer_id: Buffer | undefined;
    opt: Struct | undefined;
};