# Source: https://docs.hypermode.com/getting-started-with-hyper-commerce.md

# Quickstart: Hyper Commerce

> Learn how to instantly get started with the Hypermode Commerce template

This guide walks you through getting started with Hypermode using the
[Instant Vector Search template](https://github.com/hypermodeinc/hyper-commerce).
You’ll also learn how to customize your functions to tailor the app to your
needs.

## What's Hypermode?

[Hypermode](/introduction) is framework designed to simplify the development and
deployment of AI features and assistants. With its
[Functions SDK](/modus/overview) and runtime, developers can quickly deploy
intelligent features into production without the need for extensive data
wrangling. Hypermode supports rapid iteration, allowing you to start with a
large language model and later fine-tune smaller, open source models. Its
production-ready GraphQL API auto-generates and enables seamless integration.
Hypermode is ideal for developers looking to quickly prototype and evolve AI
capabilities.

## Quickstart

You can get started with Hypermode’s
[Instant Vector Search](https://github.com/hypermodeinc/hyper-commerce) template
using either sample data or your own, without needing to write any code or set
up a GitHub repository. This lets you explore the template and Hypermode’s
features before committing any time and effort.

### Step 1: Creating a new project

1. Visit the [Hypermode website](https://hypermode.com/login) and sign up with
   your GitHub, Google, or email address. Once signed in, you'll see the
   Hypermode projects dashboard.

2. After accessing your dashboard, click the “Create New Project” button

   <Frame>
     <img className="block" src="https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/create-project.png?fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=0cdcd258d26d374ccf3a7e131236dfdb" alt="The Hypermode projects dashboard." width="2860" height="1422" data-path="images/getting-started-guide/create-project.png" srcset="https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/create-project.png?w=280&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=e8b2af101ad1459207e36b7f98a3936f 280w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/create-project.png?w=560&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=7b688436299242024112a72d9455d9aa 560w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/create-project.png?w=840&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=68ead964c6b122b1032eee786af19aa4 840w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/create-project.png?w=1100&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=ef8d965b10d9852875f5c265c2a80c60 1100w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/create-project.png?w=1650&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=09274f3d69f7571ef867d97fb373557d 1650w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/create-project.png?w=2500&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=6a39186dea8267f735c04eafcbba65b8 2500w" data-optimize="true" data-opv="2" />
   </Frame>

3. Select “Deploy Instant Vector Search” from the options.

   <Frame>
     <img className="block" src="https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/deploy-template-dropdown.png?fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=25ba87ed22fc0a0b906e73d74753a0b0" alt="Selecting the 'Deploy instant vector search' template in the dropdown when creating a new project." width="2874" height="1420" data-path="images/getting-started-guide/deploy-template-dropdown.png" srcset="https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/deploy-template-dropdown.png?w=280&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=a4749a1fa00d20ea1753d5f3fb806497 280w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/deploy-template-dropdown.png?w=560&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=9252ee74f63bf57cf4594c0fbd3a81f0 560w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/deploy-template-dropdown.png?w=840&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=cb9530cea70baeae34598f3dcc2e4ea0 840w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/deploy-template-dropdown.png?w=1100&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=b81f77ab9f1a3e134c40cb87b1b85515 1100w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/deploy-template-dropdown.png?w=1650&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=2a7a4535d044e16eb6fb45764a6e8bb3 1650w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/deploy-template-dropdown.png?w=2500&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=61a7b742627086784e2c144c819fcca5 2500w" data-optimize="true" data-opv="2" />
   </Frame>

4. Choose between using sample data or your own data:

   <Frame>
     <img className="block" src="https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/sample-data-select.png?fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=f70e0e4c8136e5e90830415dee3bdd73" alt="Selecting to use sample data when creating the new Hypermode project." width="2866" height="1432" data-path="images/getting-started-guide/sample-data-select.png" srcset="https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/sample-data-select.png?w=280&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=715ac2aa954d99a079a6b30176839fd3 280w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/sample-data-select.png?w=560&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=309a858f6fb616caa8e2560ed6736be3 560w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/sample-data-select.png?w=840&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=29f4a604363b775d35a03c26ac137d94 840w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/sample-data-select.png?w=1100&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=b75e6ffcb802690d6b96e928bb771202 1100w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/sample-data-select.png?w=1650&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=04dd6e97e4da066e7465a7ca4a1acf63 1650w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/sample-data-select.png?w=2500&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=1d6db4f02870a14ce73e053753f22e5a 2500w" data-optimize="true" data-opv="2" />
   </Frame>

   > If you choose to use your own data, you'll need to upload it using a CSV
   > file and a Python script provided in Step 2.

5. Once created, Hypermode provisions a runtime with instant connectivity to
   shared AI models that bring the functions within your project to life. The
   source code for the project is open source, available in
   [this repository](https://github.com/hypermodeinc/hyper-commerce).

Behind the scenes, Hypermode automatically exposes the functions from the
backend directory as GraphQL APIs, allowing you to interact with them like any
other GraphQL endpoint.

### Step 2: Adding your data

If you selected sample data, your project is fully setup. You can move on to
Step 3 and immediately start exploring the project and its features. If you
chose to use your own data, follow these steps to seed your data into the
collections:

1. Ensure you have [Python](https://www.python.org/downloads/) installed on your
   machine. You can verify this by running `python --version` or
   `python3 --version` in your terminal.

2. Prepare your CSV file with the following headers:
   `Unique Id,Product Name,Category,Selling Price,About Product,Image,Num Stars,In Stock`.

3. Copy the script from
   [this file](https://github.com/hypermodeinc/hyper-commerce/blob/main/backend/extras/ecommerce_populate.py).

4. Update the script with your endpoint (located in your projects dashboard),
   API key (located in the settings tab of your Hypermode console), and the path
   to your CSV file.

5. Install the necessary dependencies:

   ```sh
   pip install requests gql requests_toolbelt pandas numpy
   ```

6. Run the script to populate your data:

   ```sh
   python3 ecommerce_populate.py
   ```

### Step 3: Exploring the Console

In the Hypermode console, you’ll see several key components of your project:

<Frame>
  <img className="block" src="https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/project-dash.png?fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=395c7b22358423d371f2f5b98529c1ea" alt="The Hypermode project dashboard." width="2866" height="1432" data-path="images/getting-started-guide/project-dash.png" srcset="https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/project-dash.png?w=280&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=3bd659c35723aed19865ffd06d1de9f8 280w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/project-dash.png?w=560&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=c450765162c481c9976de530d3bdc56f 560w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/project-dash.png?w=840&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=5ab296240fb760c68b0a507b50ad1c71 840w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/project-dash.png?w=1100&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=40f4cc4d02e4e7a1a21fc5d2c7153ff7 1100w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/project-dash.png?w=1650&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=d30fe5a0936bf0c418f10604bf68822f 1650w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/project-dash.png?w=2500&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=ff39a68ab74769defe251b4b4601142b 2500w" data-optimize="true" data-opv="2" />
</Frame>

* **[Functions](/modus/overview):** These are serverless functions written in
  AssemblyScript (a TypeScript-like language) that are automatically exposed as
  GraphQL APIs. Once deployed, you can query these functions within your app.
* **[Models](/modus/sdk/assemblyscript/models):** This section represents the AI
  models defined for your project. These models handle tasks like embedding text
  into vectors for search. Hypermode provides open source shared and dedicated
  model hosting for rapid experimentation. You can also connect to your
  preferred large language model, including OpenAI, Anthropic, and Gemini.
* **[Connections](/modus/app-manifest#connections):** You define all external
  connections, with the runtime denying all other egress for secure-by-default
  processing.
* **Endpoint:** The GraphQL endpoint for your project, which you’ll use to
  interact with your APIs and query your data.

### Step 4: Querying your data

Now that you set up, deployed, and seeded your project with data, you can test
your functions using the query interface in the Hypermode console.

1. Navigate to the Query tab in your Hypermode console to test your data.

2. Paste the following query to retrieve sample product data:

   ```graphql
   query {
     searchProducts(maxItems: 4, query: "sparkly shoes") {
       searchObjs {
         product {
           name
           description
           id
           stars
           isStocked
         }
       }
     }
   }
   ```

3. You should see the data for 4 items returned from the `searchProducts`
   endpoint that match your query, `sparkly shoes`. Feel free to experiment with
   the query—adjust the `maxItems` value to return more items, or change the
   search query to see how the returned data matches your input. Additionally,
   notice that the function ranks items based on their star rating and whether
   they're in stock.

   <Frame>
     <img className="block" src="https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/query-interface.png?fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=9b0a7e1f5178631a3d3548a882533d20" alt="The query interface." width="2864" height="1428" data-path="images/getting-started-guide/query-interface.png" srcset="https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/query-interface.png?w=280&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=9005a32ad11ea897f1d2dfb36d158d6c 280w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/query-interface.png?w=560&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=f6cf88b14bcf95dc58838833481a4626 560w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/query-interface.png?w=840&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=1c8a4b4190b4d7688e22da0130f3ec23 840w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/query-interface.png?w=1100&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=69f64f678c73741f3420333d760d1b76 1100w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/query-interface.png?w=1650&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=0283a39a347b642c9092de1c2531a9b5 1650w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/query-interface.png?w=2500&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=bc9d849a53e6b03345e1b59c2c3a7d19 2500w" data-optimize="true" data-opv="2" />
   </Frame>

### Step 5: Testing in the Frontend

Now that you've set up your project and queried your data in the console, you
can test the capability in a frontend UI.

1. Clone the repository that contains a pre-built UI for testing. You can find
   the repo
   [here](https://github.com/hypermodeinc/hyper-commerce/tree/main/frontend).

2. Retrieve your API key from the Settings section of your Hypermode console.

3. Create a `.env.local` file in the root of your project and add your API key
   and endpoint to it, like this:

   ```sh
   HYPERMODE_API_TOKEN=YOUR_API_TOKEN
   HYPERMODE_API_ENDPOINT=YOUR_API_ENDPOINT
   ```

4. **Run the project locally** by executing the following command:

   ```sh
   npm run dev
   ```

5. With the project running locally, you can now test the search capability in
   the provided UI. Try searching for products to see how your Hypermode
   project's API integrates and returns data.

> Note: The intent of this quickstart is for proof of concepts. For more
> advanced usage, such as customizing search re-ranking logic, you'll need to
> clone the template to your own repository to make and push changes. Refer to
> the next section for further instructions.

***

## Customizing the app

In this section, you’ll learn how to tailor the template to fit your specific
needs. We’ll show you how to edit your backend functions and deploy those
changes to Hypermode.

### Step 1: Clone the template repository

1. Go to the template repo
   [hyper-commerce](https://github.com/hypermodeinc/hyper-commerce).

2. Clone the repo by clicking `Use this template` in the upper-right corner and
   selecting `Create new repo.` This clones the code into your own GitHub
   repository

3. Visit the [Hypermode website](https://hypermode.com/login) and sign up with
   your GitHub, Google, or email address. Once signed in, you'll see your
   Hypermode projects dashboard.

4. In the Hypermode console, click `New Project`.

5. Select `Import a GitHub Repo`.

   <Frame>
     <img className="block" src="https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/import-github-repo.png?fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=7fc820bdcdd221516fa9912672e4f40c" alt="Selecting 'import a GitHub repo' from the dropdown." width="2872" height="1422" data-path="images/getting-started-guide/import-github-repo.png" srcset="https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/import-github-repo.png?w=280&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=66d7e5e2ca35d2ee7a1bad5a89e209de 280w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/import-github-repo.png?w=560&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=9593aca6c648a331f426c1acbdd4404a 560w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/import-github-repo.png?w=840&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=713dea08a52b5001ebbdd76811b7aa52 840w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/import-github-repo.png?w=1100&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=84ef59938222ad80df461c2948ca2b03 1100w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/import-github-repo.png?w=1650&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=f34191757b4b4009d27d22137b430499 1650w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/import-github-repo.png?w=2500&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=7e1ed1f6fe223b0af115124379db7adc 2500w" data-optimize="true" data-opv="2" />
   </Frame>

6. Choose the repo you just created.

   <Frame>
     <img className="block" src="https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/select-repo.png?fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=0a9077e8d8a75718f5c625c73764fc34" alt="Selecting the repo we want to import." width="2860" height="1430" data-path="images/getting-started-guide/select-repo.png" srcset="https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/select-repo.png?w=280&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=c2cb632d45a2f37be9a29731dcf537e0 280w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/select-repo.png?w=560&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=216a27950e6f9332d50d020a2ea9bec6 560w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/select-repo.png?w=840&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=1fc98514e9d6b1370bb2e02a9653bb2b 840w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/select-repo.png?w=1100&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=73d5b31cda77c3a62871ae85a0876d8b 1100w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/select-repo.png?w=1650&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=7cba9aabc22949bb200c2918c5e81de1 1650w, https://mintcdn.com/hypermode/KxRLwu8b3AQQ03et/images/getting-started-guide/select-repo.png?w=2500&fit=max&auto=format&n=KxRLwu8b3AQQ03et&q=85&s=b24752b2caff97d8373e74ef9c200f14 2500w" data-optimize="true" data-opv="2" />
   </Frame>

7. Click “Deploy” to finish creating your project.

8. Once deployed, your functions and collections are visible in the Hypermode
   console.

### Step 2: Seeding your data

1. Make your first commit to the repo to trigger a deployment.

2. Ensure you have [Python](https://www.python.org/downloads/) installed on your
   machine. You can verify this by running `python --version` or
   `python3 --version` in your terminal.

3. The template includes a script at `/backend/extras/ecommerce_populate.py` to
   seed your data, as well as sample data located in
   `/backend/extras/hyper_toys.csv`.

4. If you want to use your own data, replace the content of the sample CSV
   (`hyper_toys.csv`) with your own data. Make sure the headers in your CSV
   match the following headers:
   `Uniq Id,Product Name,Category,Selling Price,About Product,Image,Num Stars,In Stock`

5. Install the required dependencies by running the following command in your
   project directory:

   ```sh
   pip install -r requirements.txt
   ```

6. Edit the `ecommerce_populate.py` file to include your endpoint and API key,
   which you can find in your Hypermode dashboard.

7. Run the script to seed the data into your project:

   ```sh
   python3 ecommerce_populate.py
   ```

8. The script batch inserts the data and displays the time taken for each
   operation. Inserting the full dataset (10,000 rows) may take around 18
   minutes. If you want to test with a smaller dataset, feel free to reduce the
   size of the CSV.

### Step 3: Customizing your functions

You can modify the template to suit your needs by customizing the functions in
the `/backend/functions/assembly` directory.

#### Example: Customizing product rankings

If you'd like to rank products based solely on their star rating, without
considering whether they're in stock, follow these steps:

1. Go to the `search.ts` file and locate the
   `reRankAndFilterSearchResultObjects` function.
2. Modify the function to only rank based on the star rating, like this:

```tsx
function reRankAndFilterSearchResultObjects(
  objs: collections.CollectionSearchResultObject[],
  thresholdStars: f32,
): collections.CollectionSearchResultObject[] {
  for (let i = 0; i < objs.length; i++) {
    const starRes = collections.getText(
      consts.productStarCollection,
      objs[i].key,
    )
    const stars = parseFloat(starRes)

    objs[i].score *= stars * 0.1
  }

  objs.sort((a, b) => (a.score < b.score ? -1 : a.score > b.score ? 1 : 0))

  const filteredResults: collections.CollectionSearchResultObject[] = []
  for (let i = 0; i < objs.length; i++) {
    const starRes = collections.getText(
      consts.productStarCollection,
      objs[i].key,
    )
    const stars = parseFloat(starRes)
    if (stars >= thresholdStars) {
      filteredResults.push(objs[i])
    }
  }

  return filteredResults
}
```

#### Deploying the change

1. Once you’ve updated the function, commit the changes to your repo.
2. Any commit to the `main` branch automatically triggers a Hypermode
   deployment.
3. After deployment, when you query the `searchProducts` endpoint again, it
   ranks products solely based on their star rating.

### Step 4: Testing your functions

Once you’ve made changes to your backend functions and deployed them to
Hypermode, it's time to test the updates.

#### Test in the console IDE

In the Hypermode console, navigate to the Query tab to test your modified
functions directly. Run queries similar to the ones you used earlier to see how
the changes impact the results.

#### Run the frontend locally

The repo you cloned includes a frontend. Move into the frontend directory and
add the following values to your `.env.local` file:

```jsx
HYPERMODE_API_TOKEN = YOUR_API_TOKEN
HYPERMODE_API_ENDPOINT = YOUR_API_ENDPOINT
```

> Note: Both of these values are available in the Hypermode console

Next, just run the command `npm run dev` in your terminal to run the app
locally. Now you can test the changes you made to your backend functions.