Search Your Data

Once you've uploaded your data, you're ready to use Noematic's LLM technology to surface relevant results from your database on the basis of meaning and concepts, rather than just keywords.

Back to the e-commerce example from the previous guide, suppose the database has been populated with records corresponding to every product from a notional store (including review comments). An end-user might want to search for something to keep my workspace tidy. The search_database_records action can help surface some relevant results, even when they contain none of the words in the query.

POST
https://api.noematic.ai
Header
Content-Type
application/json
Header
Authorization
Bearer [noematic_api_key]
Body
{
  "version": "1.0",
  "view": "team",
  "action": "search_database_records",
  "data": {
    "database": {
      "id": "MtjraphUEnYS8esgGgTS12Q7zs4uyBrHw"
    },
    "query": "something to keep my workspace tidy",
    "limit": 1
  }
}

This action can take the following parameters:

  • objectdatabase
    is the database to search.
    • stringid
      is the globally unique identifier of the selected database.
  • stringquery
    indicates what you want to search for. Typically supplied by an end user through a search bar.
  • floattemperature
    is a number between 0 and 1 that indicates how much "creative liberty" a model should have in the results it surfaces. Values closer to 0 attempt to faithfully match the language used in the query, whereas values closer to 1 will maximally search for records that are on point conceptually regardless of the language used.
  • integerlimit
    is the upper limit of the number of records to surface. Defaults to 10 when not specified.
  • stringcursor
    is an optional cursor used to paginate the search results. Cursors returned in previous responses can be used in subsequent requests.
Response
Body
{
    "data": {
        "count": 1,
        "has_more": true,
        "results": [
            {
                "score": 1762.69,
                "record": {
                    "id": "FyBsGSVdRkFBAXAHHDnhdJUJdFnS9G41i",
                    "database": {
                        "id": "6pvf4DfECvc5QQsQFzvMkvdBc3eTPVEDf"
                    },
                    "content": {
                        "sku": "9ZL8WK4T4D",
                        "name": "SODIAL Wooden Desk Organizer with 5 Compartments, Desk Accessories for Office Supplies, Pen Pencil Holder, Phone Stand, Mail Sorter, Desktop Storage Box for Home, School, Office",
                        "price": 11.99,
                        "reviews": [
                            {
                                "stars": 5,
                                "author": "Danielle Rojas",
                                "comment": "Perfect size and fit for my desk. I was able to fit all of my desk accessories, pens, pencils and other little things in it. Love it!"
                            },
                            {
                                "stars": 5,
                                "author": "Kara White",
                                "comment": "Really nice desk organizer! Great size and it looks great on my desk. Keeps all my supplies organized and it's easy to access."
                            },
                            {
                                "stars": 4,
                                "author": "Nina Williams",
                                "comment": "This is a great desk organizer. It looks great and fits all of my office supplies. Easy to assemble and keep organized."
                            }
                        ],
                        "description": "The SODIAL Wooden Desk Organizer is made of high-quality wood and is designed to keep your desk neat and organized. It features 5 compartments of different sizes and shapes, perfect for organizing your office supplies such as pens, pencils, paperclips, post-it notes, and more. The desk organizer has a modern and stylish look, and will look great on any desk."
                    }
                },
                "matches": [
                    {
                        "score": 1656.74,
                        "index": {
                            "id": "8WiL1tiwvEKHzFjpz967B36A2FV381YbK"
                        },
                        "passage": "Really nice desk organizer! Great size and it looks great on my desk. Keeps all my supplies organized and it's easy to access.",
                        "highlights": [
                            "Really nice desk organizer! Great size and it looks great on my desk. Keeps all my supplies organized and it's easy to access."
                        ]
                    },
                    {
                        "score": 1605.36,
                        "index": {
                            "id": "ABq89Y4SwTJbRYZmoa3FLeZbcGgiT4SyL"
                        },
                        "passage": "The SODIAL Wooden Desk Organizer is made of high-quality wood and is designed to keep your desk neat and organized. It features 5 compartments of different sizes and shapes, perfect for organizing your office supplies such as pens, pencils, paperclips, post-it notes, and more. The desk organizer has a modern and stylish look, and will look great on any desk.",
                        "highlights": [
                            "The SODIAL Wooden Desk Organizer is made of high-quality wood and is designed to keep your desk neat and organized. It features 5 compartments of different sizes and shapes, perfect for organizing your office supplies such as pens, pencils, paperclips, post-it notes, and more. The desk organizer has a modern and stylish look, and will look great on any desk."
                        ]
                    },
                    {
                        "score": 977.79,
                        "index": {
                            "id": "8WiL1tiwvEKHzFjpz967B36A2FV381YbK"
                        },
                        "passage": "This is a great desk organizer. It looks great and fits all of my office supplies. Easy to assemble and keep organized.",
                        "highlights": [
                            "This is a great desk organizer. It looks great and fits all of my office supplies. Easy to assemble and keep organized."
                        ]
                    },
                    {
                        "score": 865.63,
                        "index": {
                            "id": "8WiL1tiwvEKHzFjpz967B36A2FV381YbK"
                        },
                        "passage": "Perfect size and fit for my desk. I was able to fit all of my desk accessories, pens, pencils and other little things in it. Love it!",
                        "highlights": [
                            "Perfect size and fit for my desk. I was able to fit all of my desk accessories, pens, pencils and other little things in it. Love it!"
                        ]
                    }
                ]
            }
        ],
        "cursor": "kxKNfes4rpka5yJywppfHhTxZ6WdVDm5CCWhcd4BDksNXeNNNDneVaWS"
    }
}

This is a large response, so it's worth inspecting in layers.

  • integercount
    is the number of records returned - it's equal to the length of the results array.
  • booleanhas_more
    indicates the presense of more results on the next page.
  • stringcursor
    is a token that can be used to request the next page of results. It's only useful if has_more is true.
  • array<object>results
    is an list of search results, grouped by record and sorted by score.
    • floatscore
      is a relative indicator of the AI model's confidence that the record associated with this result is a good match for the query.
    • objectrecord
      is a complete representation of a record.
      • Notably, the
        objectcontent
        key maps to the user-supplied JSON content of the record.
    • array<object>matches
      is a list of relevant passages from the record, sorted by score. -
      floatscore
      is a relative indicator of the AI model's confidence that this passage is a good match for the query.
      • objectindex
        indicates the identity of the index associated with this match.
        • stringid
          is the globally unique identifier of the selected index.
        • stringpassage
          is the extracted, normalized text from the record. This value is useful for presentation but not highlighting as it may be subtly different from the original text in terms of spacing and minor details.
        • array<string>highlights
          is a list of exact, non-normalized passages drawn from the record. This is useful for in-document highlighting. However each individual item may be too specific to display without context - prefer to use the passage field for presentation.

In addition to surfacing a highly relevant record, the information in this response allows you to differentially highlight different fields according to relevance.

List records without a query

You may browse through a database of records without a query using the list_database_records action.

POST
https://api.noematic.ai
Header
Content-Type
application/json
Header
Authorization
Bearer [noematic_api_key]
Body
{
  "version": "1.0",
  "view": "team",
  "action": "list_database_records",
  "data": {
    "database": {
      "id": "MtjraphUEnYS8esgGgTS12Q7zs4uyBrHw"
    },
    "limit": 1
  }
}

This action takes the same parameters as search_database_records, except query, which must not be included.

Response
Body
{
  "data": {
    "count": 2,
    "has_more": true,
    "results": [
      {
        "id": "YjZs1pALambWkahZhS34JtcfzZBYKium8",
        "database": {
          "id": "MtjraphUEnYS8esgGgTS12Q7zs4uyBrHw"
        },
        "language": "en",
        "content": {
          "sku": "1N8CZH9V7K",
          "name": "iRobot Roomba 675 Robot Vacuum, with Wi-Fi Connectivity, Works with Alexa, Good for Pet Hair, Carpets, Hard Floors, Self-Charging",
          "price": 249.99,
          "reviews": [
            {
              "stars": 5,
              "author": "Linda Nguyen",
              "comment": "This Roomba is amazing! It's so easy to use and it does a great job of cleaning the floors. It's also really quiet, which is a plus."
            },
            {
              "stars": 5,
              "author": "Garrett Smith",
              "comment": "This is a great vacuum! It's easy to use and does a great job of getting all the dirt and pet hair up. Highly recommend!"
            },
            {
              "stars": 4,
              "author": "Andrea Coleman",
              "comment": "Love this Roomba! It's easy to use, does a great job of cleaning, and is really quiet. It's also really convenient that it recharges itself."
            }
          ],
          "description": "The iRobot Roomba 675 Robot Vacuum is the perfect addition to any home. It features Wi-Fi connectivity and works with Alexa, so you can control it with your voice. It is ideal for pet hair, carpets, hard floors, and more. Plus, it automatically recharges itself, so you don't have to worry about keeping it charged."
        }
      }
    ],
    "cursor": "31CApBpewbgRRiMQd6RNpWUU6eSyxXzXTfy8LSvrK1dtK72ZwEvcTsM7Fs5Afh7dBHqzPwDNTnBBvqeimraZ8wp"
  }
}

This response has the same format as that of search_database_records, but does not include highlights for search results (as there is no query to use as a point of reference).

Next steps

Congratulations! You're now familiar enough with the key functionality of Noematic databases, records and indexes to use them in your own projects. We can't wait to hear of what you'll build. Please get in touch and let us know!

In the meantime, you might find the databases API reference useful to gain a better understanding of other lifecycle activities and actions, or contact us if you need any help.

GRAVITAS

© 2021-2025 Noematic.ai