How to set up a Discord Google Sheets lookup bot

Before you start

• Use a bot with the Pro Sheet Lookup module enabled in a Discord server you manage. Pick a test server or test channel before sharing the command with members.
• Prepare one Google Sheets tab with a nonempty header row and at least two columns. Choose one column whose values will be unique lookup keys and one or more columns that are safe to show in a Discord reply.
• Do not put private, sensitive, or access-controlled data in the tab. The module accepts a deliberately published CSV link rather than a private sheet, and a published sheet can be accessed by anyone with its link.

1. Prepare one small test tab with unique keys

   Make the first row your column headers, then add a few harmless test rows. For example, use Item as the key column and Answer as the output column. Each key should occur once. The lookup handler trims surrounding spaces and compares keys without regard to case, but it does not search partial text or choose between duplicate rows.

   Keep the tab structurally simple while testing: it needs at least two columns, nonempty headers, and rows with the same number of fields as the header. The module rejects malformed CSV data, unavailable selected columns, and duplicate lookup keys rather than returning an arbitrary row. That makes a unique key column an important part of the setup, not just a display preference.

2. Publish that tab as a CSV link

   In Google Sheets, publish the single tab you prepared to the web as Comma-separated values (.csv), then copy the resulting HTTPS link. Sheet Lookup validates a docs.google.com published-sheet URL whose path is the published CSV form and whose output parameter is csv. It can also retain a tab gid and single=true when they are part of that published URL.

   Do not substitute the ordinary editing URL, an exported file URL, a Google API URL, or a link that needs someone to sign in. The setting validation rejects those forms. Before putting the link in the bot, open it in a private browser session or ask a teammate who does not have sheet access to confirm that it is the intentionally shareable CSV tab you meant to publish.

3. Configure the published link and reply columns

   Open your bot’s Modules tab, select Sheet Lookup, choose the intended server, and paste the published CSV link. Select the column that contains the unique key, then select the fields that the reply should show. The module accepts one key column and from one to ten output columns, using zero-based column positions internally.

   Leave the command name as lookup for the first check, or choose a lowercase name made of letters, digits, hyphens, or underscores. The configured name may be one to 32 characters and cannot replace a reserved bot command. Save the settings and enable lookups for the selected server only after you have reviewed the tab’s public content.

4. Run one exact-key test in Discord

   Run /lookup and enter a value from the selected key column. With the Item and Answer example, /lookup key:rules matches a key cell containing Rules even if its capitalization or surrounding spaces differ. The selected fields return in an ephemeral reply, so only the Discord member who ran the command can see that response.

   Test both a known key and an unknown key. An unknown value receives the no-match response; it does not fall back to a partial match. If a key appears in more than one row, the module reports the duplicate instead of exposing a randomly chosen answer. Correct the sheet data first, then repeat one short test rather than adding several ambiguous rows.

5. Know what refresh and errors mean

   The module fetches the tab when a member makes a lookup. Successful data can be held in an in-memory cache for up to five minutes, subject to shorter cache instructions from the source. The reply includes the last successful refresh time, so a recently edited sheet may not appear in the very next command result.

   If the bot reports a bad link, publish the intended tab as CSV again and check that you copied the published HTTPS docs.google.com address. If it reports unavailable columns, recheck the selected positions and the header row. If it reports an oversized or invalid CSV, reduce the source to a valid table; current limits include 1 MiB, 5,000 nonblank data rows, and 100 columns. Avoid repeatedly refreshing immediately after a failure: a 30-second refresh cooldown applies.

6. Maintain a small, honest reference

   Give members a one-line instruction that names the command and the kind of key they should enter. A command such as /lookup is most useful when people know whether the key is a rule label, item code, or another exact identifier. Do not present it as a chat search: fuzzy, partial, multi-tab, formula, and write operations are outside this module’s behavior.

   Review the published tab whenever you change its headers or the data you intend to display. If you change the URL or disable the module, its in-memory cache is cleared. This is a reference lookup feature, not a storage or audit system: query history is not written to disk by the module, and a live command result should not be treated as proof that the underlying sheet is private or permanent.