Insert data

This chapter provides a detailed explanation and step-by-step guide for inserting data into an indexed composition in Inery.

Before Proceeding

Ensure that you are familiar with the indexed composition definitions covered in the Instantiate Composition section.

Data Insertion Process

Inserting data into composition involves verifying if the target object already exists within the composition. If it does not exist, the object is added using the emplace method. Below are the key steps:

• Verify if the Object Exists: Use an iterator to check for the presence of the object.
• Insert the Object: Insert the object using the emplace method if it is not already in the indexed composition.

Verify Ownership

Verify that the user calling the action is authorized. Use the require_auth method to enforce this security check.

Database Owner

[[inery::action]] void database::set( name owner, uint64_t data ) {

require_auth(owner); // Private key authorization of database owner
}

info

owner parameter is inery::name type pointing to the database owner on the ledger.
require_auth() function check whether action signature used private key of owner database.

Host Database

[[inery::action]] void database::set( name owner, uint64_t data ) {

require_auth(get_self()); // Private key authorization of contract database owner
}

Common practice

If Action does'nt contain database owner name parameter,
instead get_self() or (_self) parameters can be provided Those parameters poitns to the databse of the contract itself.

Check Primary Key Uniqueness

Define logic for checking if the owner already exists in container composition.

Add custom error handling and proceed with insertion only if all checks pass.

Set Action

Full Action for Setting Initial Owner and Data Records

[[inery::action]] void database::set( name owner, uint64_t data ) {
// Ensure that the action is authorized
    require_auth(_self); // Replace \_self with the authorized owner, if needed

    auto itr = container.find(owner.value);

    // Custom error handling if owner already exists
    check(itr == container.end(), "Error: Owner already exists in the composition.");

    // Insert the owner into the indexed composition
    container.emplace(_self, [&]( auto& u ) {
        u.owner = owner; // Set the owner name
        u.data = data; // Initialize data
    });
}

Primary Key Iterator

Find Iterator by Primary Key

auto itr = container.find(owner.value);

Breakdown

• auto itr defined itterator which will point to composition index
• container composition to query from
• .find() method to query composition instance by index key
• owner.value unsigned integer value of inery::name type

Check uniqueness

Check Whether Container Contain Primary Key

check(itr == container.end(), "Error: Owner already exists in the composition.");

Breakdown

• check contracts action, evaluate if first condition is true, if not throw error
• itr == container.end() expresion to evaulate if itterator is pointing to composition end which implies uniqueness
• Error: Error message returned if check fails.

Best Practices

• Centralized Logic: Encapsulate reusable code into private methods for better maintainability.
• Secure Authorization: Always enforce require_auth to restrict unauthorized access.
• Descriptive Errors: Use check to provide informative messages for better debugging.
• Data Integrity: Ensure all object attributes are initialized during insertion.