Skip to content
Nappai Documentation

Database

The Database component lets you work with your Notion databases directly from the Nappai dashboard. You can list the properties of a database, retrieve all its records, or create a brand‑new database inside a chosen Notion page. It talks to the Notion API, so you’ll need a Notion integration token set up in Nappai’s credentials.

How it Works

When you add this component to a workflow, it sends HTTP requests to the Notion API. Depending on the operation you choose, it either asks Notion for a list of databases, pulls all rows from a specific database, or creates a new database with the properties you define. The component can also run in Mapping Mode, which lets you feed multiple records at once and map the output of other components into its inputs.

Operations

This component offers several operations that you can select based on what you need to do. You can only use one operation at a time:

  • List Properties: Shows the properties of a specific Notion database or lists all databases if no ID is provided.
  • List: Retrieves all records from a specified Notion database.
  • Create: Creates a new database in a chosen Notion page with a specified title and properties.

To use the component, first select the operation you need in the “Operation” field.

Inputs

Mapping Mode

This component has a special mode called “Mapping Mode”. When you enable this mode using the toggle switch, an additional input called “Mapping Data” is activated, and each input field offers you three different ways to provide data:

  • Fixed: You type the value directly into the field.
  • Mapped: You connect the output of another component to use its result as the value.
  • Javascript: You write Javascript code to dynamically calculate the value.

This flexibility allows you to create more dynamic and connected workflows.

Input Fields

The following fields are available to configure this component. Each field may be visible in different operations:

  • Operation: Choose what the component will do. Only one operation can be active at a time.

    • Visible in: List Properties, List, Create

  • Database ID: Database ID to list its properties. If empty, returns a list of all available databases with their properties and IDs for easy selection.

    • Visible in: List Properties

  • Database ID: Notion Database ID where records will be listed.

    • Visible in: List

  • Database Title: Title for the new Notion database.

    • Visible in: Create

  • Mapping Mode: Enable mapping mode to process multiple data records in batch.

    • Visible in: List Properties, List, Create

  • Parent Page ID: Notion Page ID where the new database will be created.

    • Visible in: Create

  • Properties Database: Properties for the new Notion database.

    • Visible in: Create

  • Tool Name: The name of the tool that will be used when this component is connected as a tool. This name will be displayed to the agent when it selects tools to use.

    • Visible in: List Properties, List, Create

  • Tool Description: A detailed description of what this tool does. This description will help the agent understand when and how to use this tool effectively.

    • Visible in: List Properties, List, Create

  • Tools arguments metadata: Defines the arguments metadata for the tools.

    • Visible in: List Properties, List, Create

Credential
Before using this component, set up a Notion API credential in the Credentials section of Nappai. Then select that credential in the “Credential” field of the component. The credential requires a Notion Integration Token, which you can create following the instructions here.

Outputs

  • Data: The raw data returned from Notion (e.g., a list of records or database properties).
  • Tool: A tool representation that can be used by an agent in the Nappai toolkit.

Usage Example

Example 1 – List All Records in a Database

  1. Drag the Database component onto the canvas.
  2. Set Operation to List.
  3. Enter the Database ID of the database you want to read.
  4. Choose the Credential you created earlier.
  5. Run the workflow.
  6. The Data output will contain all rows from that database, ready to be passed to the next component.

Example 2 – Create a New Database

  1. Add the Database component.
  2. Set Operation to Create.
  3. Provide a Database Title (e.g., “Project Tracker”).
  4. Select the Parent Page ID where the new database should live.
  5. Choose the Properties Database to define columns (e.g., “Name”, “Status”, “Due Date”).
  6. Pick the Credential.
  7. Run the workflow.
  8. The Data output will include the new database’s ID and details, and the Tool output can be used by an agent to reference this database later.
  • NotionPage – Manage individual Notion pages.
  • NotionQuery – Run custom queries against a Notion database.
  • NotionDatabaseComponent – Base class that provides shared functionality for database operations.

Tips and Best Practices

  • Use List Properties first to discover the exact Database ID you need for other operations.
  • Enable Mapping Mode when you need to process many records at once, such as importing a CSV into Notion.
  • Keep your Notion Integration Token secret; store it in Nappai’s credential manager and never hard‑code it in a workflow.
  • When creating a new database, double‑check the Properties Database to ensure all required fields are defined.

Security Considerations

The component uses a Notion API token, which grants access to all databases and pages the integration can see. Store the token securely in Nappai’s credential manager and limit its permissions to only the databases you need. Avoid sharing the token or exposing it in logs.