Perform Find by Natural Language

Sends a natural language prompt and a list of fields on the current layout to a model, which returns a FileMaker find request, and performs a find.

Options 

• Account Name is a text expression of the AI account for this script step to use. In the current file, use the Configure AI Account script step to set up the account and assign it this name any time before this script step runs.

• Model is the name of the text generation model to use. Specify the model name as a text expression. For supported models, see FileMaker technical specifications.

• Prompt is a text expression for the natural language request or question to send to the model.

• Get specifies the type of response to retrieve from the model.

  • Found Set: Performs the find request generated by the model and updates the found set in the current window.

  • Found Set as JSON: Performs the find request generated by the model and returns the found set's data as a JSON object. Doesn't change the found set in the current window.

  • Find Request as JSON: Does not perform the find. Returns the FileMaker find request generated by the model as a JSON object.

• Prompt Template Name specifies the name of a custom prompt template configured using the Configure Prompt Template script step. Use this option to design an additional prompt to help achieve an optimal response from an AI model.

• Parameters is a text expression for a JSON object that consists of key-value pairs for additional parameters that are supported by the model provider. For example: {"temperature": 0.7, "seed": 42}. Refer to the model provider's documentation for key names of supported parameters and their valid ranges.

  The context_prompt key is a special parameter that allows you to inject additional instructions or context to the model before the main prompt. For example: {"context_prompt": "Treat 'today' as 07/07/2025"}.

• Response Target specifies the field or variable where the result of the script step is to be stored.

Originated in version 

22.0

Description 

This script step allows you to perform FileMaker find requests on your data using natural language without specifying find criteria as in the Perform Find script step. It uses an AI model to interpret a natural language prompt, analyze the fields available on the current layout, and generate an appropriate FileMaker find request (and sort order, if applicable).

The interaction between this script step and the model typically follows these steps:

1. This script step identifies all fields accessible by a find on the current layout. It sends information about these fields (similar to the output of the GetFieldsOnLayout function) along with the Prompt to the specified Model. (This includes prompts provided in an optional prompt template and the context_prompt parameter.)

2. The model analyzes the prompt and layout field information, then generates a FileMaker find request and sort order designed to retrieve the requested records.

3. This script step receives the generated find request and sort order.

4. The script step performs an action based on the Get option.

The Get option determines what happens after the model generates the find request:

Notes 

• Only fields accessible by a find on the current layout are sent to the model. For more on the criteria used to determine which fields are accessible by find, see the GetFieldsOnLayout function, which uses the same criteria as this script step. The same information sent to the model (layout name, field names, types, and descriptions) is returned by GetFieldsOnLayout.

• Field comments you enter in the Manage Database dialog are included with the field information sent to the model. To improve the model's ability to generate useful find requests, you can use the comment to explain the purpose of the field. See Defining and changing fields. For more on controlling which fields' comments are sent to the model, see the GetFieldsOnLayout function.

• If you specify a Prompt Template Name, this script step uses the template configured via the Configure Prompt Template script step. Prompt templates can use constants like :schema: (replaced with layout field information), :question: (replaced with Prompt), and :context: (replaced with the context_prompt parameter in Parameters).

• This script step can be used for multilingual finds, as AI models can operate on multiple languages.

• When no relevant records are found, a message is returned in the Response Target (if used), and the Get(LastError) function returns error 401 ("No records match the request").

• This script step can't perform finds that require aggregate functions (for example, finding the record with the highest value in a field). However, the model may return a find request that includes sort criteria to help identify such records (for example, sorting records by the Price field in descending order).

Example 1 

Configures an AI account, goes to the Contacts layout, then uses this script step to search for contacts named "Alea" in the current layout. This script step sends the findable fields on the current layout and the prompt "Find contacts named Alea" to the model. The model sends back a find request (possibly a request for "Alea" in the Name field), and this script step performs the find, updating the found set in the current window.

Configure AI Account [ Account Name: "my-account" ; Model Provider: OpenAI ; API key: "sk-..." ]

Go to Layout [ "Contacts" (Contacts) ; Animation: None ]

Perform Find by Natural Language [ Account Name: "my-account" ; Model: "gpt-4o" ; Prompt: "Find contacts named Alea" ; Get: Found Set ]

Example 2 

Configures an AI account, prompts the user for a query, then performs the find and returns the data of the resulting found set as JSON in the $$FoundSetData variable. Queries are performed on the current layout.

Configure AI Account [ Account Name: "my-account" ; Model Provider: OpenAI ; API key: "sk-..." ]

Go to Layout [ "Products" (Products) ; Animation: None ]

Show Custom Dialog [ "Find products:" ; $$UserPrompt ]

If [ not IsEmpty ( $$UserPrompt ) ]

    Perform Find by Natural Language [ Account Name: "my-account" ; Model: "gpt-4o" ; Prompt: $$UserPrompt ; Get: Found Set as JSON ; Response Target: $$FoundSetData ]
    
    Show Custom Dialog [ "Found Set Data:" ; JSONFormatElements ( $$FoundSetData ) ]
    
End If

Possible output stored in $$FoundSetData (formatted using JSONFormatElements), assuming the prompt was "Find products with price less than 6, and sort them in descending order by price":

{
    "messages" : 
    [
        {
            "code" : "0",
            "message" : "OK"
        }
    ],
    "response" : 
    {
        "data" : 
        [
            {
                "fieldData" : 
                {
                    "Price" : 5.99,
                    "ProductID" : 107,
                    "ProductName" : "Safety Glasses",
                    "Status" : "In Stock"
                },
                "modId" : "0",
                "portalData" : {},
                "recordId" : "61"
            },
            {
                "fieldData" : 
                {
                    "Price" : 5.5,
                    "ProductID" : 122,
                    "ProductName" : "Putty Knife",
                    "Status" : "In Stock"
                },
                "modId" : "0",
                "portalData" : {},
                "recordId" : "76"
            }
        ],
        "dataInfo" : 
        {
            "database" : "Ordering System",
            "foundCount" : 2,
            "layout" : "Products",
            "returnedCount" : 2,
            "table" : "Products",
            "totalRecordCount" : 42
        }
    }
}

Example 3 

Configures an AI account, then configures a custom prompt template that uses the predefined prompt for a find request. The predefined prompt describes the JSON format for a find request and includes the following: Use the following information as context: \":context:\".

After going to the Products layout and setting the $$Today variable to a natural language phrase to use for context later, this script step substitutes the :context: constant used in the prompt template with the value of the context_prompt key in Parameters. It then sends that along with the prompt "Find records created today sorted by product name" to the model.

The model returns the find request as a JSON object in the $$FindRequestJSON variable, which you can use for debugging purposes.

Configure AI Account [ Account Name: "my-account" ; Model Provider: OpenAI ; API key: "sk-..." ]

Configure Prompt Template [ Template Name: "FindToday" ; Model Provider: OpenAI ; Template Type: Find Request ; Find Request Prompt: "Generate and only return a JSON layout query to perform a find request..." ]

Go to Layout [ "Products" (Products) ; Animation: None ]

Set Variable [ $$Today ; Value: "Today is " & Get ( CurrentDate ) ]

Perform Find by Natural Language [ Account Name: "my-account" ; Model: "gpt-4o" ; Prompt: "Find records created today sorted by product name" ; Get: Find Request as JSON ; Parameters: JSONSetElement ( "{}" ; "context_prompt" ; $$Today ; JSONString ) ; Response Target: $$FindRequestJSON ]

Show Custom Dialog [ "Generated Find Request" ; JSONFormatElements ( $$FindRequestJSON ) ]

Possible output stored in $$FindRequestJSON (formatted using JSONFormatElements), assuming the current date is 07/07/2025 and the layout has CreationDate and ProductName fields:

{
    "layouts" : "Products",
    "query" : 
    [
        {
            "Products::CreationDate" : "07/07/2025"
        }
    ],
    "sort" : 
    [
        {
            "fieldName" : "Products::ProductName",
            "sortOrder" : "ascend"
        }
    ]
}

Related topics 

• GetFieldsOnLayout function

• Perform Find script step

• Perform Semantic Find script step

• Perform SQL Query by Natural Language script step

• GetFieldsOnLayout function

• Script steps reference