Implement sys::approximate_count() (#8692)

It takes a schema::ObjectType, so it is called like
`sys::approximate_count(introspect Card)`.
This is because the implementation works by querying the `reltuples`
field of `pg_class`, and it really only makes sense for getting a
full table. Having it take `anytype` and special casing would
create weird discontinuities where the simple case worked like this
and complex cases have a correctness or performance cliff.

By default it includes all descendant types too; the ignore_subtypes
parameter changes that.

Fixes #4164.

Author: msullivan

docs/reference/stdlib/sys.rst

@@ -11,6 +11,9 @@ System
 .. list-table::
     :class: funcoptable
 
+    * - :eql:func:`sys::approximate_count`
+      - :eql:func-desc:`sys::approximate_count`
+
     * - :eql:func:`sys::get_version`
       - :eql:func-desc:`sys::get_version`
 
@@ -36,6 +39,43 @@ System
 ----------
 
 
+.. eql:function:: sys::approximate_count( \
+                      type: schema::ObjectType, \
+                      NAMED ONLY ignore_subtypes: std::bool=false, \
+                  ) -> int64
+
+    Return an approximate count of the number of objects belonging to
+    a given type.
+
+    The ``type`` argument is a ``schema::ObjectType`` representing the
+    type to query.  It can be most easily obtained with the
+    :eql:op:`introspect` operator.
+
+    By default, the count includes all subtypes of the provided type as well.
+    If ``ignore_subtypes`` is true, then it includes only the type itself.
+
+    The value is based on postgres statistics, and may not be accurate.
+
+    .. code-block:: edgeql-repl
+
+        db> select sys::approximate_count(introspect schema::Type);
+        {278}
+        db> select sys::approximate_count(introspect schema::Type, ignore_subtypes:=True);
+        {0}
+        db> select schema::ObjectType {
+        ... name,
+        ... cnt := sys::approximate_count(schema::ObjectType, ignore_subtypes:=True),
+        ... };
+        {
+           schema::ObjectType {name: 'default::Issue', cnt: 4},
+           schema::ObjectType {name: 'default::User', cnt: 2},
+           ...
+        }
+
+
+----------
+
+
 .. eql:function:: sys::get_version() -> tuple<major: int64, \
                                               minor: int64, \
                                               stage: sys::VersionStage, \

edb/buildmeta.py

@@ -57,7 +57,7 @@
 # The merge conflict there is a nice reminder that you probably need
 # to write a patch in edb/pgsql/patches.py, and then you should preserve
 # the old value.
-EDGEDB_CATALOG_VERSION = 2025_05_09_00_00
+EDGEDB_CATALOG_VERSION = 2025_05_09_00_01
 EDGEDB_MAJOR_VERSION = 7
 
 

edb/lib/sys.edgeql

@@ -405,3 +405,15 @@ sys::__pg_or(a: OPTIONAL std::bool, b: OPTIONAL std::bool) -> std::bool
         SELECT a OR b;
     $$;
 };
+
+
+CREATE FUNCTION
+sys::approximate_count(
+    type: schema::ObjectType,
+    NAMED ONLY ignore_subtypes: std::bool=false,
+) -> int64
+{
+    SET volatility := 'Stable';
+    USING SQL FUNCTION 'edgedb.approximate_count';
+    set impl_is_strict := false;
+};

edb/pgsql/delta.py

@@ -1528,6 +1528,8 @@ def get_dummy_func_call(
             param_type = param.get_type(schema)
             pg_at = self.get_pgtype(cobj, param_type, schema)
             args.append(f'NULL::{qt(pg_at)}')
+            if isinstance(param_type, s_objtypes.ObjectType):
+                args.append(f'NULL::uuid')
 
         return f'{q(*name)}({", ".join(args)})'
 

edb/pgsql/metaschema.py

@@ -1802,6 +1802,54 @@ def __init__(self) -> None:
         )
 
 
+# We create this version first (since it is used by the stdlib), and
+# then replace it with the real version later.
+class ApproximateCountDummy(trampoline.VersionedFunction):
+    text = '''
+        SELECT 0
+    '''
+
+    def __init__(self) -> None:
+        super().__init__(
+            name=('edgedb', 'approximate_count'),
+            args=[
+                ('ignore_subtypes', ('bool',)),
+                ('type', ('uuid',)),
+                ('type_type', ('uuid',), "NULL"),
+            ],
+            returns=('bigint',),
+            volatility='stable',
+            text=self.text,
+        )
+
+
+class ApproximateCount(trampoline.VersionedFunction):
+    text = '''
+        SELECT coalesce(sum(reltuples::bigint), 0) AS estimate
+        FROM pg_class pc
+        WHERE pc.relname IN (
+          SELECT oa.source::text
+          FROM edgedb_VER."_SchemaObjectType__ancestors" oa
+          WHERE oa.target = type AND not ignore_subtypes
+          UNION
+          select type::text
+        ) AND pc.reltuples >= 0;
+    '''
+
+    def __init__(self) -> None:
+        super().__init__(
+            name=('edgedb', 'approximate_count'),
+            args=[
+                ('ignore_subtypes', ('bool',)),
+                ('type', ('uuid',)),
+                ('type_type', ('uuid',), "NULL"),
+            ],
+            returns=('bigint',),
+            volatility='stable',
+            text=self.text,
+        )
+
+
 class IssubclassFunction(trampoline.VersionedFunction):
     text = '''
         SELECT
@@ -5312,6 +5360,7 @@ def get_bootstrap_commands(
         dbops.CreateFunction(FTSToRegconfig()),
         dbops.CreateFunction(PadBase64StringFunction()),
         dbops.CreateFunction(ResetQueryStatsFunction(False)),
+        dbops.CreateFunction(ApproximateCountDummy()),
     ]
 
     non_trampolined = [
@@ -8709,6 +8758,7 @@ async def generate_support_functions(
         dbops.CreateFunction(IssubclassFunction()),
         dbops.CreateFunction(IssubclassFunction2()),
         dbops.CreateFunction(GetSchemaObjectNameFunction()),
+        dbops.CreateFunction(ApproximateCount(), or_replace=True),
     ]
     commands.add_commands(cmds)
 

tests/test_edgeql_functions.py

@@ -9406,3 +9406,26 @@ async def test_edgeql_functions_complex_types_04(self):
             ['https://edgedb.com', '~/screenshot.png'],
             sort=True,
         )
+
+    async def test_edgeql_functions_approximate_count(self):
+        await self.assert_query_result(
+            '''
+            select sys::approximate_count(introspect Issue);
+            ''',
+            [int],
+        )
+
+        await self.assert_query_result(
+            '''
+            select sys::approximate_count(
+                introspect schema::Object, ignore_subtypes := True);
+            ''',
+            [0],
+        )
+
+        val = await self.con.query_single(
+            '''
+            select sys::approximate_count(introspect schema::Object);
+            '''
+        )
+        self.assertGreater(val, 0)