While using one of your favorite apps, have you ever run into something like this?

<QuickVid src="https://static.convex.dev/stack/search-sanity/bad-search.m4v" caption="Old content is searchable, but new content is… not?" />

It’s pretty reasonable to expect that once you add a document to your Notion workspace, the search box will find it! What’s going on here?

# Unsavory search secrets

You may be surprised to learn that there’s nothing particularly unusual about what Notion is doing. In most systems, backend search architectures are structured just so:

<QuickVid src="https://static.convex.dev/stack/search-sanity/search-arch-animation.m4v" use_poster caption="The search query can arrive after the document is saved, but before the search index is updated" />

In this common design, the system that *stores* your records is separate from the system that *indexes* them for search. Specialized systems are chained together, such as MySQL for the database and Elasticsearch for full-text search.

So there is inherently a delay in the pipeline that connects storage and search, and your users might experience a temporary inconsistency–a stored document not yet searchable, just as we saw with Notion. This inconsistency is often only a few seconds, but sometimes can be minutes or hours.

While the ease of leveraging several ready-to-go systems for each task may feel like a pragmatic decision for a software team, it really sucks that it “leaks” internal architectural choices in the form of a confusing user experience.

# Fancy concepts, simple expectations

At <QuickConvex />, we love deep infrastructure concepts like strong consistency and [ACID](https://stack.convex.dev/dont-drop-acid). But not because distributed systems papers are riveting beach reads. Instead, because we believe the mark of a great platform is facilitating the easy creation of software that Just Works. Convex projects should automatically do what the developer and user expect.

And that’s why Convex’s search is *transactional:* search indexes in Convex guarantee that the very moment a document is committed to the database, that document shows up in search results. User expectations met!

And while we’re at it, Convex developers expect that everything in our platform is seamlessly reactive. So we made search reactive, too.

# What “just works” looks like

Let’s use Convex to search through a sample of Wikipedia articles!

As a prerequisite, we retrofitted the Convex [tutorial chat app](https://docs.convex.dev/tutorial/welcome-to-convex) by loading 100,000 random Wikipedia articles with the [command line import tool](https://docs.convex.dev/using/cli#import-a-file-into-convex). We assigned the page body to the `body` field and the title to the `author` field of the messages table.

Time to get searching! First, we need to create the search index using [Convex’s schema definition](https://docs.convex.dev/using/schemas). Let’s create an index called “search_body” that is indexing the `body` field. We’ll do this by using the `searchIndex` method on the schema object:

```tsx
import { defineSchema, defineTable, s } from "convex/schema";

export default defineSchema({
  messages: defineTable({
    body: s.string(),
    author: s.string(),
  }).searchIndex("search_body", {
    searchField: "body",
  }),
});
```

Then, we can easily use this search index in our app’s [query functions](https://docs.convex.dev/using/database-queries) by calling our query’s `withSearchIndex` method.

```tsx
export default query(async ({ db }, query) => {
  const results = await db
    .query("messages")
    .withSearchIndex("search_body", q => q.search("body", query))
    .take(5);
  return results;
});
```

Finally, as usual in React + Convex apps, we’ll leverage the Convex library’s `useQuery` hook to [attach this backend query function](https://docs.convex.dev/using/writing-convex-functions#defining-convex-functions) to a component rendering a list of results:

<QuickVid src="https://static.convex.dev/stack/search-sanity/good-search.m4v" caption="Instantly reactive, fully consistent ACID-compliant search." />

This principled take on search is just one of the many ways in which Convex nudges your projects toward the [pit of success](https://blog.codinghorror.com/falling-into-the-pit-of-success/). So start a new project today, try out transactional search, and [come show us what you built](https://convex.dev/community)!

Your document is safely stored, but search is coming up empty? Inconsistent search systems can really confuse users! Don't worry–in Convex, transactional search indexing ensures that users always get what they expect and your apps just work.

Searching for Sanity

On 3/1/23 OpenAI released an API for Chat-GPT. In this post, we’ll walk through putting together a full-stack chat app, and add some features. 

We’ll use React and Vite, though any React framework works. We’ll use <QuickConvex /> as the backend, where our server-side functions will run, and where we’ll store our app’s data. 

To see this in action, the code is [here](https://github.com/ianmacartney/convex-chat-gpt), and a running version is [here](https://convex-chat-gpt-f6rq.vercel.app/) (for now).

To run this yourself, you’ll need to make an [OpenAI account](https://platform.openai.com/signup) and [get an API key](https://platform.openai.com/account/api-keys).

If you’re familiar with Convex, you can skip ahead to step 2.

# 0. Bootstrap a Vite React app

If you don’t already have an app, we can make one:

```bash
npm create vite@latest
```

I picked `convex-chatgpt` as the project name, `React` as the framework, and `Javascript` as the variant.

At this point, if we run:

```bash
npm install
npm run dev
```

we have a locally running webapp.

Let’s change `src/App.jsx` to list messages and have a form to submit messages:

<details>
<summary>App.jsx</summary>
    
    ```tsx
    import {useState} from "react";
    import "./App.css";
    
    function App() {
      const messages = [
        {author: "user", body: "Hello, world"},
      ];
      const sendMessage = body =>
        console.log("Trying to send: " + body);
      const [newMessageText, setNewMessageText] =
        useState("");
    
      return (
        <div className="App">
          {messages.map((message, i) => (
            <p key={i}>
              <span>{message.author}: </span>
              <span style={{ whiteSpace: "pre-wrap" }}>
                {message.body ?? "..."}
              </span>
            </p>
          ))}
          <form onSubmit={(e) => {
            e.preventDefault();
            setNewMessageText("");
            sendMessage(newMessageText);
          }}>
            <input
              value={newMessageText}
              onChange={e => setNewMessageText(e.target.value)}
              placeholder="Write a message…"
            />
            <input type="submit" value="Send" disabled={!newMessageText} />
          </form>
        </div>
      );
    }
    
    export default App;
    ```
</details>    

At this point, we have an app that shows a static list of messages and logs to the console when trying to send a message.

# 1. Add Convex

This is similar to the Convex [quickstart](https://docs.convex.dev/quickstart). In a new terminal (leave the other one running `npm run dev`):

```bash
npm install convex
npx convex init
```

If you haven’t used convex before, you’ll be prompted to log in, create an account, etc. I picked `convex-chatgpt` as the project name.

Let’s add the ability to send messages and list messages. We will add functions that run in Convex (on a server) that will read and write to the database with a [query](https://docs.convex.dev/understanding/convex-fundamentals/functions#query-functions) and [mutation](https://docs.convex.dev/understanding/convex-fundamentals/functions#mutation-functions).

Add `convex/messages.ts`:

```jsx
import { query, mutation } from "./_generated/server";

export const list = query(async ({ db }) => {
  return await db.query("messages").take(100);
});

export const send = mutation(async ({ db }, body) => {
  await db.insert("messages", {
    body,
    author: "user",
  });
  const botMessageId = await db.insert("messages", {
    author: "assistant",
  });
});
```

In a separate terminal from the one running `npm run dev`, run `npx convex dev`. This will deploy these functions to your new Convex backend, and as you edit the functions, it will automatically re-deploy. This will ask you to save the deployment URL into your `.env` and `.env.local` files: these point at your convex backends for your production and development deployments. We’ll just be working with the development deployment.

To access Convex from inside React, you’ll need to add a `<ConvexProvider>` context at the top level of your app. Edit `main.jsx`:

```jsx
...
import { ConvexProvider, ConvexReactClient } from "convex/react";

const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);

ReactDOM.createRoot(document.getElementById("root")).render(
  <React.StrictMode>
    <ConvexProvider client={convex}>
      <App />
    </ConvexProvider>
  </React.StrictMode>,
);
```

We can then use these functions from `App.jsx`:

```jsx
function App() {
  const messages = useQuery("messages:list") || [];
  const sendMessage = useMutation("messages:send");
	...
```

Great! Now we have messages being written to and from the database. Try it out! Those new to Convex will be surprised to see that adding new messages will automatically result in the `useQuery("messages:list")` hook returning new messages. This is part of the magic of Convex. Learn more about it [here](https://docs.convex.dev/understanding/convex-fundamentals/functions#reactivity). 

You can check out your data in the dashboard: `npx convex dashboard`. 

You may note that the query and mutation are named by the `filename:function`. See more about this [here](https://docs.convex.dev/using/writing-convex-functions#defining-convex-functions).

You’ll notice every time we send a message, there’s a “…” message from the assistant. Next let’s update that message from chatGPT. 

# 2. Send a message to the ChatGPT API

So far we’ve been working with a [query](https://docs.convex.dev/understanding/convex-fundamentals/functions#query-functions) and [mutation](https://docs.convex.dev/understanding/convex-fundamentals/functions#mutation-functions), which are Convex functions that interact with the database. In order to interact with external services, we need to do that in an “[action](https://docs.convex.dev/understanding/convex-fundamentals/functions#action-functions)” - which is a Convex function that isn’t inside a deterministic environment and isn’t part of a database transaction. This frees us to do things with side effects, such as making requests to OpenAI’s API. We’ll do this in a few steps.

## Fetching messages to send to ChatGPT

In our `send` mutation, we can grab the latest 10 messages to send to ChatGPT using a database query:

```jsx
export const send = mutation(async ({ db }, body) => {
  //... insert messages to the table
  const messages = await db
    .query("messages")
    .order("desc")
    .filter((q) => q.neq(q.field("body"), null))
    .take(21);
  messages.reverse();
  return { messages, botMessageId };
});
```

This orders messages in descending order (sorted by creation time unless you use a different [index](https://docs.convex.dev/using/indexes)), filters out messages with no body (for instance, the new placeholder system message), and takes the first 21 (which are the 21 most recent messages). It then reverses the list so it’s ordered in ascending time order. I picked 21 so that we’ll have 10 pairs of user/bot messages, followed by the latest prompt. It returns the messages to be used as input to the chat completion API, which we'll add next.

## Creating the action

We’ll use the `openai` npm package. You can install it with:

```bash
npm install openai
```

Make a new file: `convex/actions/openai.js`:

```jsx
import { Configuration, OpenAIApi } from "openai";
import { action } from "../_generated/server";

export const chat = action(async ({ runMutation }, body) => {
  const { messages, botMessageId } = await runMutation("messages:send", body);
  const fail = async (reason) => throw new Error(reason);
  // Grab the API key from environment variables
  // Specify this in your dashboard: `npx convex dashboard`
  const apiKey = process.env.OPENAI_API_KEY;
  if (!apiKey) {
    await fail("Add your OPENAI_API_KEY as an env variable");
  }
  const configuration = new Configuration({ apiKey });
  const openai = new OpenAIApi(configuration);

  const openaiResponse = await openai.createChatCompletion({
    model: "gpt-3.5-turbo",
    messages: [
      {
        role: "system",
        content: instructions,
      },
      ...messages.map(({ body, author }) => ({
        role: author,
        content: body,
      })),
    ],
  });
  if (openaiResponse.status !== 200) {
    await fail("OpenAI error: " + openaiResponse.statusText);
  }
  const body = openaiResponse.data.choices[0].message.content;
	console.log("Response: " + body);
});
```

This will first send the messages with the send mutation we modified, getting in return the list of messages and message ID to update with the bot’s message. It will then make a request to the `gpt-3.5-turbo` model, passing in one system message with instructions (hard-coded for now), followed by each message. We’re turning our body & author fields into “role” and “content”. See their docs [here](https://platform.openai.com/docs/guides/chat) for more details on the API.

## Add your API key to the dashboard

To authenticate requests to OpenAI, you’ll need to add your [API key](https://beta.openai.com/account/api-keys) to the Convex dashboard, so your action (which runs on Convex’s servers) has access to it. Go to your dashboard with `npx convex dashboard` and on the left panel go into Settings and add the key with the name `OPENAI_API_KEY`. While you’re there, you can add it as an env variable to both your production and development deployments by toggling the dropdown in the left panel.

![Dashboard side panel](https://cdn.sanity.io/images/ts10onj4/production/8aa4d6a158df734f3d64e1eb15333528e37c92e5-263x392.png?w=300)


## Triggering the action from the UI

We can change our call to `useQuery("messages:send")` to

```jsx
const sendMessage = useAction("actions/openai:chat");
```

Note the action is addressed by the path to the file (`actions/openai`) and the function (`chat`). The API is the same (taking one argument, `body`), so it’s a drop-in replacement!

At this point, if you run it, it will send a request to ChatGPT and console.log the response. Convex prints Convex function logs to the browser’s console, though you can also see them in the [dashboard](https://dashboard.convex.dev/), to prove to yourself it’s running in the cloud. Now let’s show them in the UI.

## Updating the message with the reply

In order to get the response into the chat message, we’ll want to update the empty placeholder message we added. Treat each call to a mutation as a transaction. Once we called our first mutation, the messages were committed to the database and the UI could show the new messages before doing the slow call to OpenAI. Once we get the response, we update the bot’s message and the UI will update automatically via the `messages:list` query. We’ll add a new mutation in the `convex/messages.js` file:

```jsx
export const update = mutation(async ({ db }, messageId, patch) => {
  await db.patch(messageId, patch);
});
```

This patches the specified message. You could pass in `{body: "hi"}` to change the message’s body to “hi,” for example. Since the first mutation returned the `botMessageId`, we can use that from the action in `convex/actions/openai.js`:

```jsx
export const chat = action(async ({ runMutation }, body) => {
  const { messages, botMessageId } = await runMutation("messages:send", body);

  // Call OpenAI

  await runMutation("messages:update", botMessageId, {
    body: openaiResponse.data.choices[0].message.content,
    // Track how many tokens we're using for various messages
    usage: openaiResponse.data.usage,
    updatedAt: Date.now(),
    // How long it took OpenAI
    ms: Number(openaiResponse.headers["openai-processing-ms"]),
  });
});
```

While we’re here, we can store a bunch of interesting data into the message along with the body. Convex’s database is flexible enough to store [strings, numbers, javascript objects, `Map`s, etc.](https://docs.convex.dev/using/types) while also letting you nail down a [schema](https://docs.convex.dev/using/schemas) later to get typescript types, autocomplete, etc. 

🎉 Now you have chatGPT replying to your messages!

# Summary

In this post, we made a full-stack web app to chat with OpenAI’s ChatGPT API. Let us know [in Discord](https://convex.dev/community) what you think, and if you’d like to see some extensions:

- [Customizing the identity you’re talking to.](https://stack.convex.dev/adding-personality-to-chatgpt-3)
- [Moderating the identities and messages to prevent harmful content.](https://stack.convex.dev/moderating-chatgpt-content-full-stack)
- Create new message threads. (See the [code](https://github.com/ianmacartney/convex-chat-gpt) for how it's done!)

Let's build a full-stack chat app to talk to ChatGPT on its new API!

Building a Full-Stack ChatGPT app

SQL has been a part of computing for a very long time, and SQL-based database systems underly most of the world's applications. But recently, developers have been clamoring for something better, and it's time to move on.

It's not you, it's SQL

I’ve been using the Dashboard a lot while developing my own apps, so I asked Arnold, the engineer behind the Dashboard, to put together some tips for using it effectively. I hope you find it as useful as I do!

So you’ve got your <QuickConvex /> app set up, eh? Maybe you’ve worked through the [tutorial](https://docs.convex.dev/tutorial/welcome-to-convex) or tried out one of our [demo apps](https://github.com/get-convex/convex-demos). Perhaps you’ve even built your own app already!

Now that you’re familiar with Convex, I’d like to show you some of the tools you can use in the dashboard to level up your development productivity.

## 1. Iterate on and test new functions

To iterate quickly, it’s nice to be able to isolate your code and test backend functionality on its own, without needing to integrate into the frontend. Good news — you can do this straight from the Convex dashboard’s [Functions page](https://docs.convex.dev/using/dashboard#testing-functions). To get started, click the “Run function” button found near your function’s implementation. From there, you can subscribe to live query results and run one-off actions and mutations. If you’re running `npx convex dev` in your code repo, any edits to the functions will sync automatically to your dev instance, so you can quickly edit and re-run your functions as you iterate.

<QuickVid src="https://static.convex.dev/stack/5-dashboard-tricks/run-functions.webm" caption="An example of testing a “list messages” and “send message” Convex function using the dashboard" />

## 2. Seed and prototype data

Before you’ve gotten your functions fully wired up, you can use the dashboard to create tables and documents.

Convex provides two types of editors for editing documents — the default editor provides a simpler view of your data, broken down by field. Clicking the “Edit as JavaScript” button allows you to edit data using the same syntax you would in JavaScript code.

<QuickVid src="https://static.convex.dev/stack/5-dashboard-tricks/prototyping.webm" caption="An example of adding a `channels` table to my chat app project, and associating an existing message with a new channel." />

## 3. Search and destroy — data filters

Got a heap of data to sift through in your tables? Dashboard filters have got you covered. Find this handy button on the [Data page](https://docs.convex.dev/using/dashboard#filtering-documents), and use it to narrow down the results shown to just the documents you’re looking for.

<QuickVid src="https://static.convex.dev/stack/5-dashboard-tricks/filters.webm" caption="An example of filtering a list of chat messages by channel ID" />

## 4. Upload files

Did you know that in addition to documents, Convex allows you to store and retrieve files, such as images and videos? Well now ya do — you can [upload files programmatically](https://docs.convex.dev/using/file-storage) in your Convex functions, or upload individual files using the [File storage tab on the Data page](https://docs.convex.dev/using/dashboard#file-storage).

<QuickVid src="https://static.convex.dev/stack/5-dashboard-tricks/upload-file.webm" caption="Uploading a file to convex" />

## 5. Edit your app’s configuration live

Since Convex queries are [fully reactive](https://docs.convex.dev/understanding/convex-fundamentals/functions#reactivity), updating your data in the dashboard will inform all clients subscribed to the related data that their queries should be re-run. See [this post](https://stack.convex.dev/feature-gating) on using Convex to implement a basic kill switch.

Did you know you can use the Convex Dashboard to run functions, enter seed data, filter & delete data, upload files, and more?

5 Dashboard Tricks

Learn With Jason

You can build a database-powered app with end-to-end type safety and real-time updates without needing to learn how to manage databases. This tutorial will show you how.


Type-safe, data-driven apps, even if databases freak you out

Yet Another Infrastructure Group

Hosted by Ian & Alex, with Alana (Readyset), Hojjat (Deltastream), Jamie (Convex).

Convex and the future of streaming infrastructure

Convex

Dynamic application developers need global state management, not a database.

James (@jamesacowling) presents his talk from the HYTRADBOI 2022 database conference on how Convex is rethinking how app developers manage global state.

Data Interactivity in the Serverless Future (HYTRADBOI 2022)

Jamstack TV

Today, a new wave of innovation is making databases approachable for developers without requiring a specialized skillset, opening the door to a whole new category of ambitious web experiences. In this panel, you’ll hear from the people pushing the boundaries of database technology and learn what’s possible — and what’s coming.

Jamstack Conf 2022 Panel: The Future of Databases

Sujay (@sujayakar314) walks through how easy it is to build a dynamic web app with global state on Convex. Join the Convex beta at https://convex.dev.

Building reactive web apps on Convex