ORM docs added to guides.

.github/scripts/docs/preview-deploy.js

@@ -0,0 +1,191 @@
+const DOCS_SITE_REPO = {
+  org: "edgedb",
+  repo: "edgedb.com",
+  ref: "new-new-docs",
+};
+
+module.exports = async ({ github, context }) => {
+  const { VERCEL_TOKEN, VERCEL_TEAM_ID } = process.env;
+
+  if (!VERCEL_TOKEN || !VERCEL_TEAM_ID) {
+    throw new Error(
+      `cannot run docs preview deploy workflow, ` +
+        `VERCEL_TOKEN or VERCEL_TEAM_ID secrets are missing`
+    );
+  }
+
+  const prBranch = context.payload.pull_request.head.ref;
+  const commitSHA = context.payload.pull_request.head.sha;
+  const shortCommitSHA = commitSHA.slice(0, 8);
+
+  const existingComments = (
+    await github.rest.issues.listComments({
+      owner: context.repo.owner,
+      repo: context.repo.repo,
+      issue_number: context.issue.number,
+    })
+  ).data;
+
+  const commentHeader = `### Docs preview deploy\n`;
+  let commentMessage = commentHeader;
+
+  let updateComment = existingComments.find(
+    (c) =>
+      c.performed_via_github_app?.slug === "github-actions" &&
+      c.body?.startsWith(commentHeader)
+  );
+
+  let deploymentError = null;
+  let deployment;
+  try {
+    deployment = await vercelFetch("https://api.vercel.com/v13/deployments", {
+      name: "edgedb-docs",
+      gitSource: {
+        type: "github",
+        ...DOCS_SITE_REPO,
+      },
+      projectSettings: {
+        buildCommand: `EDGEDB_REPO_BRANCH=${prBranch} EDGEDB_REPO_SHA=${commitSHA} yarn vercel-build`,
+      },
+    });
+
+    commentMessage += `\n🔄 Deploying docs preview for commit ${shortCommitSHA}:\n\n<https://${deployment.url}>`;
+  } catch (e) {
+    deploymentError = e;
+    commentMessage += `\n❌ Failed to deploy docs preview for commit ${shortCommitSHA}:\n\n\`\`\`\n${e.message}\n\`\`\``;
+  }
+
+  commentMessage += `\n\n(Last updated: ${formatDatetime(new Date())})`;
+
+  if (updateComment) {
+    await github.rest.issues.updateComment({
+      owner: context.repo.owner,
+      repo: context.repo.repo,
+      comment_id: updateComment.id,
+      body: commentMessage,
+    });
+  } else {
+    updateComment = (
+      await github.rest.issues.createComment({
+        owner: context.repo.owner,
+        repo: context.repo.repo,
+        issue_number: context.issue.number,
+        body: commentMessage,
+      })
+    ).data;
+  }
+
+  if (deploymentError) {
+    throw new Error(`Docs preview deployment failed: ${e.message}`);
+  }
+
+  let i = 0;
+  while (i < 40) {
+    await sleep(15_000);
+    i++;
+
+    const status = (
+      await vercelFetch(
+        `https://api.vercel.com/v13/deployments/${deployment.id}`
+      )
+    ).status;
+
+    const latestComment = await github.rest.issues.getComment({
+      owner: context.repo.owner,
+      repo: context.repo.repo,
+      comment_id: updateComment.id,
+    });
+
+    if (!latestComment.data.body.includes(shortCommitSHA)) {
+      console.log("Skipping further updates, new deployment has started");
+      return;
+    }
+
+    if (status === "READY" || status === "ERROR" || status === "CANCELED") {
+      await github.rest.issues.updateComment({
+        owner: context.repo.owner,
+        repo: context.repo.repo,
+        comment_id: updateComment.id,
+        body: `${commentHeader}${
+          status === "READY"
+            ? `\n✅ Successfully deployed docs preview for commit ${shortCommitSHA}:`
+            : `\n❌ Docs preview deployment ${
+                status === "CANCELED" ? "was canceled" : "failed"
+              } for commit ${shortCommitSHA}:`
+        }\n\n<https://${deployment.url}>\n\n(Last updated: ${formatDatetime(
+          new Date()
+        )})`,
+      });
+      if (status !== "READY") {
+        throw new Error(
+          `Docs preview deployment failed with status ${status}: https://${deployment.url}`
+        );
+      }
+      return;
+    }
+  }
+
+  await github.rest.issues.updateComment({
+    owner: context.repo.owner,
+    repo: context.repo.repo,
+    comment_id: updateComment.id,
+    body: `${commentHeader}
+❌ Timed out waiting for deployment status to succeed or fail for commit ${shortCommitSHA}:\n\n<https://${
+      deployment.url
+    }>\n\n(Last updated: ${formatDatetime(new Date())})`,
+  });
+  throw new Error("Timed out waiting for deployment status to succeed or fail");
+};
+
+async function vercelFetch(url, body) {
+  const { VERCEL_TOKEN, VERCEL_TEAM_ID } = process.env;
+  const _url = new URL(url);
+  url = `${_url.origin}${_url.pathname}?${new URLSearchParams({
+    teamId: VERCEL_TEAM_ID,
+  })}`;
+
+  let res;
+  try {
+    res = await fetch(url, {
+      body: body ? JSON.stringify(body) : undefined,
+      headers: {
+        Authorization: `Bearer ${VERCEL_TOKEN}`,
+        "Content-Type": body ? "application/json" : undefined,
+      },
+      method: body ? "post" : "get",
+    });
+  } catch (e) {
+    throw new Error(`vercel api request failed: ${e}`);
+  }
+
+  if (res.ok) {
+    return await res.json();
+  } else {
+    let body;
+    try {
+      body = await res.text();
+    } catch (e) {
+      // ignore
+    }
+    throw new Error(
+      `vercel api request failed: ${res.status} ${res.statusText}, ${body}`
+    );
+  }
+}
+
+function formatDatetime(date) {
+  return date.toLocaleString("en-US", {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+    hour: "numeric",
+    minute: "numeric",
+    second: "numeric",
+    hourCycle: "h24",
+    timeZoneName: "short",
+  });
+}
+
+function sleep(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

docs/ai/index.rst

@@ -12,18 +12,18 @@ AI
     python
     reference
 
-:edb-alt-title: Using EdgeDB AI
+:edb-alt-title: Using Gel AI
 
-EdgeDB AI allows you to ship AI-enabled apps with practically no effort. It
+|Gel| AI allows you to ship AI-enabled apps with practically no effort. It
 automatically generates embeddings for your data. Works with OpenAI, Mistral
 AI, Anthropic, and any other provider with a compatible API.
 
 
 Enable extension in your schema
 ===============================
 
-AI is an EdgeDB extension. To enable it, you will need to add the extension
-to your app’s schema:
+AI is a |Gel| extension. To enable it, you will need to add the extension
+to your app's schema:
 
 .. code-block:: sdl
 
@@ -34,12 +34,12 @@ Extension configuration
 =======================
 
 The AI extension may be configured via our UI or via EdgeQL. To use the
-built-in UI, access it by running ``edgedb ui``. If you have the extension
+built-in UI, access it by running :gelcmd:`ui`. If you have the extension
 enabled in your schema as shown above and have migrated that schema change, you
 will see the "AI Admin" icon in the left-hand toolbar.
 
 .. image:: images/ui-ai.png
-    :alt: The EdgeDB local development server UI highlighting the AI admin
+    :alt: The Gel local development server UI highlighting the AI admin
           icon in the left-hand toolbar. The icon is two stars, one larger and
           one smaller, the smaller being a light pink color and the larger
           being a light blue when selected.
@@ -69,7 +69,7 @@ Provider" button, selecting the appropriate API, and pasting your key in the
 "Secret" field.
 
 .. image:: images/ui-ai-add-provider.png
-    :alt: The "Add Provider" form of the EdgeDB local development server UI.
+    :alt: The "Add Provider" form of the Gel local development server UI.
           On the left, the sidebar navigation for the view showing Playground,
           Prompts, and Providers options, with Provider selected (indicated
           with a purple border on the left). The main content area shows a
@@ -85,7 +85,7 @@ You may alternatively configure a provider via EdgeQL:
 
 .. code-block:: edgeql
 
-    configure current database
+    configure current branch
     insert ext::ai::OpenAIProviderConfig {
       secret := 'sk-....',
     };
@@ -104,13 +104,13 @@ We have provider config types for each of the three supported APIs:
 Usage
 =====
 
-Using EdgeDB AI requires some changes to your schema.
+Using |Gel| AI requires some changes to your schema.
 
 
 Add an index
 ------------
 
-To start using EdgeDB AI on a type, create an index:
+To start using |Gel| AI on a type, create an index:
 
 .. code-block:: sdl-diff
 
@@ -124,8 +124,8 @@ To start using EdgeDB AI on a type, create an index:
 
 In this example, we have added an AI index on the ``Astronomy`` type's
 ``content`` property using the ``text-embedding-3-small`` model. Once you have
-the index in your schema, :ref:`create <ref_cli_edgedb_migration_create>` and
-:ref:`apply <ref_cli_edgedb_migration_apply>` your migration, and you're ready
+the index in your schema, :ref:`create <ref_cli_gel_migration_create>` and
+:ref:`apply <ref_cli_gel_migration_apply>` your migration, and you're ready
 to start running queries!
 
 .. note::
@@ -154,13 +154,13 @@ can define an AI index on an expression:
 .. note:: When AI indexes aren't working…
 
     If you find your queries are not returning the expected results, try
-    inspecting your instance logs. On an EdgeDB Cloud instance, use the "Logs"
+    inspecting your instance logs. On a |Gel| Cloud instance, use the "Logs"
     tab in your instance dashboard. On local or :ref:`CLI-linked remote
-    instances <ref_cli_edgedb_instance_link>`, use ``edgedb instance logs -I
-    <instance-name>``. You may find the problem there.
+    instances <ref_cli_gel_instance_link>`, use :gelcmd:`instance logs -I
+    <instance-name>`. You may find the problem there.
 
     Providers impose rate limits on their APIs which can often be the source of
-    AI index problems. If index creation hits a rate limit, EdgeDB will wait
+    AI index problems. If index creation hits a rate limit, |Gel| will wait
     the ``indexer_naptime`` (see the docs on :ref:`ext::ai configuration
     <ref_ai_reference_config>`) and resume index creation.
 
@@ -209,13 +209,13 @@ Use RAG via HTTP
 ----------------
 
 By making an HTTP request to
-``https://<edgedb-host>:<port>/branch/<branch-name>/ai/rag``, you can generate
+``https://<gel-host>:<port>/branch/<branch-name>/ai/rag``, you can generate
 text via the generative AI API of your choice within the context of a type with
 a deferred embedding index.
 
 .. note::
 
-    Making HTTP requests to EdgeDB requires :ref:`authentication
+    Making HTTP requests to |Gel| requires :ref:`authentication
     <ref_http_auth>`.
 
 .. code-block:: bash
@@ -224,7 +224,7 @@ a deferred embedding index.
         "query": "What color is the sky on Mars?",
         "model": "gpt-4-turbo-preview",
         "context": {"query":"select Astronomy"}
-      }' https://<edgedb-host>:<port>/branch/<branch-name>/ai/rag
+      }' https://<gel-host>:<port>/branch/<branch-name>/ai/rag
     {"response": "The sky on Mars is red."}
 
 Since LLMs are often slow, it may be useful to stream the response. To do this,
@@ -243,14 +243,14 @@ add ``"stream": true`` to your request JSON.
 Use RAG via JavaScript
 ----------------------
 
-``@edgedb/ai`` offers a convenient wrapper around ``ext::ai``. Install it with
-``npm install @edgedb/ai`` (or via your package manager of choice) and
+``@gel/ai`` offers a convenient wrapper around ``ext::ai``. Install it with
+``npm install @gel/ai`` (or via your package manager of choice) and
 implement it like this example:
 
 .. code-block:: typescript
 
-    import { createClient } from "edgedb";
-    import { createAI } from "@edgedb/ai";
+    import { createClient } from "gel";
+    import { createAI } from "@gel/ai";
 
     const client = createClient();