How to feed the data of an auxiliary table

After defining the fields, the table is ready to receive records. How to register them depends on the option chosen under How the table will be fed:

Feeding	How the records arrive	Ideal for
Manual input	Typed in one by one on the web or imported from an .xlsx or .csv spreadsheet.	Small lists or lists that rarely change, or an initial load from a spreadsheet.
Via API	Sent by an external system, which replaces the whole table contents on each request.	Lists that already exist in another system (HR, ERP, customer register) and must always match it.

The feeding mode can be changed later, through the Edit option in the table menu.

1. Manual input

In Manual input tables, the Data block sits below the Fields and shows the table records, with a search (Search the records) and pagination.

Adding, editing and removing records

1. In the Data block, click Add item;
2. In the New record panel, fill in the fields. Only the Key is required;
3. Click Save.

To fix a record, use the Edit record button on its row; to delete it, Remove record.

Adding a record manually

Importing a spreadsheet

To register many records at once, import a spreadsheet:

1. Prepare the file:
   • .xlsx (Excel) or .csv format, up to 50 MB. In .xlsx files, only the first sheet is read;
   • the first row must have the column headers, written with the Title or the Internal name of each field (uppercase, lowercase and accents do not matter);
   • each following row is a record;
2. In the Data block, click Import spreadsheet and choose the file;
3. Wait for the message with the result, for example "120 records imported successfully".

What happens during the import:

• New record (a key that does not exist yet): it is created;
• Existing record (same key): it is updated with the spreadsheet values;
• Records that are not in the spreadsheet stay in the table: the import does not delete anything. To remove records, use Remove record;
• Rows with problems (for example, without the key or with text in a Number field) are skipped, and the rest are imported. The message tells how many rows were rejected, for example "118 records imported, 2 rows rejected".

Columns that match no field

If the file has a column whose header matches no field, or matches more than one, nothing is imported. The system tells which columns caused the problem: rename them with the Title or the Internal name of a field, or remove them, and import again.

Numbers in .csv files

In .csv files, write decimal numbers with a dot (10.5), not a comma. In .xlsx files, it is enough for the cell to be formatted as a number.

2. Feeding via API

In Via API tables, the records are sent by an external system, usually set up by the IT team. Instead of the Data block, the table shows two tabs:

• Data ingestion via API: the address to send to, an example of the data and an example command, built with the table fields, plus the access token;
• Data: the records received, for reference only.

Each request replaces the whole table

"Each request replaces the whole table contents: records missing from the payload are removed." In other words, the external system must always send the complete list, and not only what changed.

Example: the table has Anna, Bruno and Carla. To add Daniel, the request must carry Anna, Bruno, Carla and Daniel. If the system sends only Daniel, the table is left with Daniel alone: Anna, Bruno and Carla are removed.

Generate the token

The token is the password the external system uses to send the data. Each table has its own.

1. In the Data ingestion via API tab, click Generate token;
2. Copy the token immediately and store it in a safe place, such as a password vault: "for security it will not be shown again";
3. After that, the panel only shows the last characters of the active token, for example "Active token, ending in a1b2".

Button	When to use
Generate new token	The token was lost or exposed. The current token stops working right away, and the system that sends the data stops until it is updated with the new one.
Revoke token	Stop data ingestion. No request is accepted until a new token is generated.
Empty table	Remove every record from the table, keeping the defined fields.

For the IT team

The request is a POST to the address shown under Endpoint (for example, https://api2.hashdata.app/v1/aux-tables/ingest), with the token in the X-HD-Aux-Table-Token header and, in the body, a JSON list with one object per record. The keys of each object are the Internal names of the fields:

curl -X POST 'https://api2.hashdata.app/v1/aux-tables/ingest' \
  -H 'Content-Type: application/json' \
  -H 'X-HD-Aux-Table-Token: YOUR_TOKEN' \
  -d '[
    { "employee_id": "1001", "name": "Ana Souza", "department": "Production", "capacity": 40 },
    { "employee_id": "1002", "name": "Bruno Lima", "department": "Quality", "capacity": 35 }
  ]'

Request rules:

• Complete list on every request. Records whose key does not appear in the request are removed from the table. To empty it, use the Empty table button or the PUT .../aux-tables/truncate route, with the same header; a request with an empty list is rejected;
• Only the table fields. A key that is not the Internal name of a field causes the row to be rejected. Empty or null fields are not stored;
• Numbers must be sent as JSON numbers (40), not as text with a comma;
• Limits: up to 100,000 records per request, up to 50 fields per record, texts of up to 10,000 characters and at most 2 requests per minute per token;
• Response: the number of records stored (upserted) and the list of rejected rows (rejectedRows), each with the reason. Rejected rows do not delete the record that already existed with the same key.

While the table structure is being changed

During the reprocessing of a structure change, requests are rejected. The external system should try again a few minutes later.

3. Common problems

What you see	What to do
"Define the table fields before adding records."	Save the table fields before adding or importing records.
"The file has columns that match no field of this table"	Rename the columns with the Title or the Internal name of the fields, or remove them.
"The file exceeds the maximum size of 50 MB."	Split the spreadsheet into smaller files and import one at a time.
"The file is invalid or empty."	Check that the file is .xlsx or .csv and that the first sheet has a header and records.
Some rows were rejected	Check that all of them have the Key filled in and that Number fields contain only numbers.
I do not see the Add item button	The table is Via API: records only arrive from the external system. Change it to Manual input under Edit, if appropriate.
The external system stopped sending data	The token may have been revoked or replaced. Generate a new one and hand it to the IT team.
Records disappeared after an API request	The request did not include those records. Each request must contain the complete list.

Next steps

• Learn more about how to use the table in a form;
• Learn more about how to limit the records per workspace.