Implement Row Seeker within Forms

db/records.py

@@ -119,6 +119,26 @@ def search_records_from_table(
     return result
 
 
+def list_by_record_summaries(
+    conn,
+    table_oid,
+    limit=500,
+    offset=0,
+    search=None,
+    table_record_summary_templates=None,
+):
+    result = db_conn.exec_msar_func(
+        conn,
+        'list_by_record_summaries',
+        table_oid,
+        limit,
+        offset,
+        search,
+        _json_or_none(table_record_summary_templates),
+    ).fetchone()[0]
+    return result
+
+
 def delete_records_from_table(conn, record_ids, table_oid):
     """
     Delete records from table by id.

db/sql/00_msar_all_objects_table.sql

@@ -1143,6 +1143,9 @@ INSERT INTO msar.all_mathesar_objects VALUES
   ('msar', 'msar.list_column_privileges_for_current_role(regclass,smallint)', 'FUNCTION', NULL),
   ('msar', 'msar.list_database_privileges_for_current_role(oid)', 'FUNCTION', NULL),
   ('msar', 'msar.list_db_priv()', 'FUNCTION', NULL),
+  ('msar', 'msar.list_by_record_summaries(oid,integer,integer,jsonb,text,jsonb,boolean,boolean)', 'FUNCTION', NULL),
+  ('msar', 'msar.list_by_record_summaries(oid,integer,integer,text,jsonb,boolean)', 'FUNCTION', NULL),
+  ('msar', 'msar.list_by_record_summaries(oid,integer,integer,text,jsonb)', 'FUNCTION', NULL),
   ('msar', 'msar.list_records_from_table(oid,integer,integer,jsonb,jsonb,jsonb,boolean)', 'FUNCTION', NULL),
   ('msar', 'msar.list_records_from_table(oid,integer,integer,jsonb,jsonb,jsonb,boolean,jsonb)', 'FUNCTION', NULL),
   ('msar', 'msar.list_roles()', 'FUNCTION', NULL),

db/sql/05_msar.sql

@@ -5627,6 +5627,49 @@ END;
 $$ LANGUAGE plpgsql;
 
 
+CREATE OR REPLACE FUNCTION msar.list_by_record_summaries(
+  tab_id oid,
+  limit_ integer,
+  offset_ integer,
+  search_ text DEFAULT NULL,
+  table_record_summary_templates jsonb DEFAULT NULL
+) RETURNS jsonb
+LANGUAGE plpgsql STABLE
+AS $$
+DECLARE
+  search_where_clause text := '';
+  final_sql text;
+  result_json jsonb;
+BEGIN
+  IF search_ IS NOT NULL AND search_ <> '' THEN
+    search_where_clause := format(' WHERE summary ILIKE %L', '%'||search_||'%');
+  END IF;
+
+  final_sql := format(
+    $q$
+    WITH
+      all_record_summaries AS ( %1$s ),
+      filtered AS ( SELECT * FROM all_record_summaries %2$s ),
+      sorted AS ( SELECT * FROM filtered ORDER BY summary LIMIT %3$s OFFSET %4$s )
+    SELECT
+      json_build_object(
+        'count', (SELECT count(*) FROM filtered),
+        'results', coalesce(json_agg(sorted), '[]')
+      )
+    FROM sorted
+    $q$,
+    /* 1 */ msar.build_record_summary_query_for_table(tab_id, NULL, table_record_summary_templates),
+    /* 2 */ search_where_clause,
+    /* 3 */ limit_,
+    /* 4 */ offset_
+  );
+
+  EXECUTE final_sql INTO result_json;
+  RETURN result_json;
+END;
+$$;
+
+
 CREATE OR REPLACE FUNCTION
 msar.get_tab_col_info_map(tab_col_map jsonb)
 RETURNS jsonb AS $$/*

db/sql/test_sql_functions.sql

@@ -4889,11 +4889,11 @@ BEGIN
   rel_id := 'atable'::regclass::oid;
   RETURN NEXT is(
     msar.patch_record_in_table( rel_id, 2, '{"2": 10}'),
-    $p${
+    '{
       "results": [{"1": 2, "2": 10, "3": "sdflfflsk", "4": null, "5": "[1, 2, 3, 4]"}],
       "linked_record_summaries": null,
       "record_summaries": null
-    }$p$
+    }'
   );
 END;
 $$ LANGUAGE plpgsql;
@@ -4907,11 +4907,11 @@ BEGIN
   rel_id := 'atable'::regclass::oid;
   RETURN NEXT is(
     msar.patch_record_in_table( rel_id, '2', '{"2": 10}'),
-    $p${
+    '{
       "results": [{"1": 2, "2": 10, "3": "sdflfflsk", "4": null, "5": "[1, 2, 3, 4]"}],
       "linked_record_summaries": null,
       "record_summaries": null
-    }$p$
+    }'
   );
 END;
 $$ LANGUAGE plpgsql;
@@ -4925,11 +4925,11 @@ BEGIN
   rel_id := 'atable'::regclass::oid;
   RETURN NEXT is(
     msar.patch_record_in_table( rel_id, 2, '{"2": 10, "4": {"a": "json"}}'),
-    $p${
+    '{
       "results": [{"1": 2, "2": 10, "3": "sdflfflsk", "4": "{\"a\": \"json\"}", "5": "[1, 2, 3, 4]"}],
       "linked_record_summaries": null,
       "record_summaries": null
-    }$p$
+    }'
   );
 END;
 $$ LANGUAGE plpgsql;
@@ -6788,3 +6788,87 @@ BEGIN
   );
 END;
 $$ LANGUAGE plpgsql;
+
+-- msar.list_by_record_summaries --------------------------------------------------------------------
+
+CREATE OR REPLACE FUNCTION test_list_by_record_summaries()
+RETURNS SETOF TEXT AS $$
+BEGIN
+  CREATE TABLE vehicles (
+    id int primary key,
+    name text,
+    wheel_count int
+  );
+
+  -- Empty table behavior
+  RETURN NEXT is(
+    msar.list_by_record_summaries('vehicles'::regclass, 10, 0),
+    '{"count": 0, "results": []}'
+  );
+
+  INSERT INTO vehicles VALUES
+    (1, 'Car', 4),
+    (2, 'Truck', 4),
+    (3, 'Unicycle', 1),
+    (4, 'Bicycle', 2),
+    (5, 'Tricycle', 3),
+    (6, 'Boat', 0),
+    (7, 'Semi', 18),
+    (8, 'Airplane', 10);
+
+  -- Basic test
+  RETURN NEXT is(
+    msar.list_by_record_summaries('vehicles'::regclass, 2, 0),
+    '{
+      "count": 8,
+      "results": [
+        {"key": 8, "summary": "Airplane"},
+        {"key": 4, "summary": "Bicycle"}
+      ]
+    }'
+  );
+
+  -- Pagination
+  RETURN NEXT is(
+    msar.list_by_record_summaries('vehicles'::regclass, 3, 3),
+    '{
+      "count": 8,
+      "results": [
+        {"key": 1, "summary": "Car"},
+        {"key": 7, "summary": "Semi"},
+        {"key": 5, "summary": "Tricycle"}
+      ]
+    }'
+  );
+
+  -- Search query
+  RETURN NEXT is(
+    msar.list_by_record_summaries('vehicles'::regclass, 2, 0, 'cycle'),
+    '{
+      "count": 3,
+      "results": [
+        {"key": 4, "summary": "Bicycle"},
+        {"key": 5, "summary": "Tricycle"}
+      ]
+    }'
+  );
+
+  -- Empty search query
+  RETURN NEXT is(
+    msar.list_by_record_summaries('vehicles'::regclass, 2, 0, 'NOPE'),
+    '{"count": 0, "results": []}'
+  );
+
+  -- Search in custom record summary template
+  RETURN NEXT is(
+    msar.list_by_record_summaries(
+      'vehicles'::regclass,
+      2,
+      0,
+      '18 wheels',
+      format('{ "%s": [ [2], " with ", [3], " wheels" ] }', 'vehicles'::regclass::oid)::jsonb
+    ),
+    '{"count": 1, "results": [{"key": 7, "summary": "Semi with 18 wheels"}]}'
+  );
+END;
+$$ LANGUAGE plpgsql;

db/tests/wrapper/test_exec_wrappers.py

@@ -88,7 +88,15 @@ def visit_Call(self, node):
 
 @pytest.mark.parametrize("_,exec_sql_func_name,exec_sql_arg_count", find_exec_calls_in_project("db/"))
 def test_db_wrapper(get_msar_func_names, _, exec_sql_func_name, exec_sql_arg_count):
-    """Tests to make sure every SQL function is correctly wired up."""
+    """
+    Tests to make sure every SQL function is correctly wired up.
+
+    If this test is failing, compare the number of arguments in your function
+    definitions across the following code locations:
+
+    - The source code of the function, as defined in the DB layer
+    - The python wrapper function that calls that DB layer function
+    """
     if exec_sql_func_name != 'drop_all_msar_objects':
         assert exec_sql_func_name in get_msar_func_names.keys()
         assert exec_sql_arg_count in get_msar_func_names[exec_sql_func_name]

docs/docs/api/methods.md

@@ -146,11 +146,14 @@
       - add
       - delete
       - replace
+      - list_related_records
       - FormInfo
       - FieldInfo
       - AddFormDef
       - AddOrReplaceFieldDef
       - ReplaceableFormDef
+      - ListRelatedRecordsResponse
+      - SummarizedRecordReference
 
 ## Records
 

mathesar/rpc/forms.py

@@ -1,12 +1,23 @@
 """
 Classes and functions exposed to the RPC endpoint for managing forms.
 """
-from typing import Optional, TypedDict, Literal
+from typing import Optional, TypedDict, Literal, Any
 
 from modernrpc.core import REQUEST_KEY
 
+from db.records import list_by_record_summaries
+
 from mathesar.rpc.decorators import mathesar_rpc_method
-from mathesar.utils.forms import create_form, get_form, list_forms, delete_form, replace_form, get_form_source_info
+from mathesar.utils.forms import (
+    create_form,
+    delete_form,
+    get_form_by_token,
+    get_form_source_info,
+    get_form,
+    list_forms,
+    replace_form,
+)
+from mathesar.utils.tables import get_table_record_summary_templates
 
 
 class FieldInfo(TypedDict):
@@ -220,6 +231,37 @@ class ReplaceableFormDef(AddFormDef):
     id: int
 
 
+class SummarizedRecordReference(TypedDict):
+    """
+    A summarized reference to a record, typically used in foreign key fields.
+
+    Attributes:
+        key: A unique identifier for the record.
+        summary: The record summary
+    """
+    key: Any
+    summary: str
+
+
+class ListRelatedRecordsResponse(TypedDict):
+    """
+    Response for listing related records for a foreign key field.
+
+    Attributes:
+        count: The total number of records matching the criteria.
+        results: A list of summarized record references, each containing a key and a summary.
+    """
+    count: int
+    results: list[SummarizedRecordReference]
+
+    @classmethod
+    def from_dict(cls, d):
+        return cls(
+            count=d["count"],
+            results=d["results"],
+        )
+
+
 @mathesar_rpc_method(name="forms.add", auth="login")
 def add(*, form_def: AddFormDef, **kwargs) -> FormInfo:
     """
@@ -309,3 +351,47 @@ def replace(*, new_form: ReplaceableFormDef, **kwargs) -> FormInfo:
     user = kwargs.get(REQUEST_KEY).user
     form_model = replace_form(new_form, user)
     return FormInfo.from_model(form_model)
+
+
+@mathesar_rpc_method(name="forms.list_related_records", auth="anonymous")
+def list_related_records(
+        *,
+        form_token: str,
+        field_key: str,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        search: Optional[str] = None,
+        **kwargs,
+) -> ListRelatedRecordsResponse:
+    """
+    List records for selection via the row seeker
+
+    Args:
+        form_token: The unique token of the form.
+        field_key: The key of the foreign key field for which to list related records.
+        limit: Optional limit on the number of records to return.
+        offset: Optional offset for pagination.
+        search: Optional search term to filter records.
+
+    Returns:
+        The requested records, along with some metadata.
+    """
+
+    form = get_form_by_token(form_token)
+    database_id = form.database.id
+    form_field = form.fields.get(key=field_key)
+    if form_field.kind != "foreign_key":
+        raise ValueError(f"Field {field_key} is not a foreign key field.")
+
+    table_oid = form_field.related_table_oid
+
+    with form.connection as conn:
+        record_info = list_by_record_summaries(
+            conn,
+            table_oid,
+            limit=limit,
+            offset=offset,
+            search=search,
+            table_record_summary_templates=get_table_record_summary_templates(database_id),
+        )
+    return ListRelatedRecordsResponse.from_dict(record_info)

mathesar/tests/rpc/test_endpoints.py

@@ -283,6 +283,11 @@
         "forms.replace",
         [user_is_authenticated]
     ),
+    (
+        forms.list_related_records,
+        "forms.list_related_records",
+        []
+    ),
     (
         records.add,
         "records.add",

mathesar/utils/forms.py

@@ -128,6 +128,10 @@ def get_form(form_id):
     return form_model
 
 
+def get_form_by_token(form_token):
+    return Form.objects.get(token=form_token)
+
+
 def get_form_source_info(form_token):
     form_model = Form.objects.get(token=form_token)
     if form_model: