> For the complete documentation index, see [llms.txt](https://apogeejs.gitbook.io/apogeejs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apogeejs.gitbook.io/apogeejs/getting-started.tutorials/populating-a-data-table.md).

# Populating a Data Table

{% hint style="info" %}
It might be helpful watching the *Tour of Apogee* video on the [Getting Started](/apogeejs/master.md) page to do this tutorial.
{% endhint %}

**Create a new workspace**

**In the new workspace, add a data table with a static value:** ([example](https://www.apogeejs.com/apogee.html?url=https://www.apogeejs.com/web/examples/TableBasics_StaticTable.json))

1. Create a data table name "year". Use the default data view *colorized*.
2. Inside the "data" view of the table place the number *1980*.

**Add a data table with a simple formula:** ([example](https://www.apogeejs.com/apogee.html?url=https://www.apogeejs.com/web/examples/TableBasics_SimpleFormula.json)**)**

1. Create a data table named "url".
2. Inside the "formula" view, add the single line formula below, creating a URL using a javascript string template literal and the value from our "year" table. In a formula, tables are treated as normal javascript variables.

```javascript
return `https://www.apogeejs.com/web/examples/population/us${year}.json`;
```

 **Add a data table with an asynchronous formula - web request:** ([example](https://www.apogeejs.com/apogee.html?url=https://www.apogeejs.com/web/examples/TableBasics_Completed.json))

1. Create a data table named "populationData".
2. Inside the formula view, add a single line formula, requesting a json object from the given URL.

```javascript
return apogee.net.jsonRequest(url);
```

> The formula for a data table must be synchronous. If you want to do an asynchronous action, like a web request, you can return a Promise object from the formula.
>
> While the promise is pending, a yellow banner is displayed.When the promise resolves, on success the banner will clear. On failure an error will be displayed.
>
> This function in the code above is from the apogee library. It is like the javascript "fetch" function except its promise returns either the body of the request, converted into a json object, or it throws an error.

 **Modify a data table so it throws an error:** ([example](https://www.apogeejs.com/apogee.html?url=https://www.apogeejs.com/web/examples/TableBasics_Error.json)*)*

1. On the "url" table, modify the formula so it just throws an error.

```javascript
throw new Error("This is an error we generated ourselves!");

//return `https://www.apogeejs.com/web/examples/population/us${year}.json`;
```

> In apogee, errors are displayed to the user as a red banner on the table. Additionally, any table that depends on that table will also show a red banner with the message that a table on which it depends has an error.

**Modify a data table so it returns INVALID VALUE:** ([example](https://www.apogeejs.com/apogee.html?url=https://www.apogeejs.com/web/examples/TableBasics_InvalidValue.json))

1. On the "url" table, modify the formula so it just returns apogee.util.INVALID\_VALUE.

```javascript
return apogee.util.INVALID_VALUE;

//return `https://www.apogeejs.com/web/examples/population/us${year}.json`;
```

> If you return apogee.util.INVALID\_VALUE, the table displays a gray banner. Additionally, any table that depends on that table will also show a gray banner. This can be done to prevent downstream tables from trying to calculate a value if one table does not have a valid value.
>
> The purpose of this feature is so you don't have to do null checking or the equivalent in your functions. This is especially handy when you have a long cascade of tables based on a single value. Apogee does the check for you, and does not execute the code if it depends on a table with an INVALID VALUE.
>
> This does not depend one whether the executed path will use the variable, only if it is present. What this means is you *can't* do an INVALID VALUE check and make a decision based on that. That is a feature that should possibly added in a future version (along with a way of handling an error in parent table).

**Finished!**

This concludes the tutorial. From this you should have learned some of the different ways of assigning a value to a data table.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apogeejs.gitbook.io/apogeejs/getting-started.tutorials/populating-a-data-table.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.