How to programmatically enable "Page Query" (Map Series) on Annotation Layers?

[MarcelSt-Germain]

Hello community,

I am writing a Python script in ArcGIS Pro to automate the generation of annotations using the Tiled Labels To Annotation tool. The generation part works perfectly.

However, I am stuck on the final step. I have hundreds of resulting annotation layers, and I need to programmatically enable the Page Query property (found in Layer Properties > Page Query) for each of them.

The Goal: I need the script to:

Enable the Page Query (Filter based on Map Series).

Set the matching field to "TileID".

The Issue: I cannot find the correct ArcPy method or the valid CIM path to toggle this specific setting. I attempted to modify the layer definition using lyr.getDefinition('V3') by looking for pageDefinition or CIMPageDefinition, but the changes do not persist or the property seems inaccessible for these specific annotation layers.

Does anyone have a working code snippet (CIM or ArcPy) to enable the Page Query and set the field name?

Environment:

ArcGIS Pro 3.x

Python 3

Thank you for your help!

[VenkataKondepati]

Yes — you don’t need CIM for this in Pro 3.x. arcpy.mp.Layer has a native method called setPageQuery() that toggles Layer Properties → Page Query and sets the matching field in one shot

A working pattern looks like this (run in the Pro Python window / as a script tool in the same project):

import arcpy

TILE_FIELD = "TileID"   # field in each annotation feature class/layer
MATCH = True            # True = match current page name, False = inverse

aprx = arcpy.mp.ArcGISProject("CURRENT")

for lyt in aprx.listLayouts():
    ms = getattr(lyt, "mapSeries", None)
    if not ms or not ms.enabled:
        continue

    # Page Query only applies to layers in the MapFrame used by the Map Series
    mf = ms.mapFrame
    m = mf.map

    updated = 0
    failed = 0

    for lyr in m.listLayers():
        # Annotation layers are feature layers in most projects; keep this filter simple and safe
        if not lyr.isFeatureLayer:
            continue

        try:
            # Enable Page Query + set matching field
            lyr.setPageQuery(TILE_FIELD, MATCH)  # <-- the key call
            updated += 1
        except Exception as ex:
            failed += 1
            arcpy.AddWarning(f"Skipped: {lyr.longName} | {ex}")

    arcpy.AddMessage(f"[{lyt.name}] Page Query set on {updated} layers (failed: {failed}).")

aprx.save()

A couple of “gotchas” (these bite everyone)
Page Query is only honored when the layer is inside the MapFrame that your Map Series references. If you’re updating layers in a different map/frame, nothing will appear to happen even though the property is set.

setPageQuery() expects the field in the layer whose values match the Map Series page name field (from the index layer). So your TileID strategy works best when your Map Series “Name Field” is also effectively TileID (or produces the same values).

You can verify what’s currently set using lyr.pageQuery (it returns a tuple with fieldName and match).