Enhancement: Making behaviour of TAPService.search() configurable (Or default to async where available)

[stvoutsin]

Summary of problem

Currently TAPService.search() is just an alias to run_sync(), which means that all queries use sync execution regardless of service capabilities.
I think for many/most service providers this may not be the optimal choice, and at least in our case we'd prefer if search uses run_async.

# Current implementation
search = run_sync

Proposed Solutions

I see two potential approaches for implementing this enhancement:

Approach 1: Automatic async-first (capability-based default)

Make search() automatically check capabilities and use async when available:

def search(self, query, *, language="ADQL", maxrec=None, uploads=None, 
           force_sync=False, **keywords):
    if force_sync or not self._supports_async():
        return self.run_sync(query, language=language, maxrec=maxrec, uploads=uploads, **keywords)
    else:
        return self.run_async(query, language=language, maxrec=maxrec, uploads=uploads, **keywords)

This approach does change the default-behaviour (though I would say it is backward compatible) so that queries will be run async but that shouldn't be visible to users.

With this option we get the benefits and stability of asynchronous job execution and the benefit is that it does not require any changes to the API.

Approach 2: Opt-in via service parameter

Add prefer_async parameter to TAPService.__init__():

class TAPService:
    def __init__(self, baseurl, *, capability_description=None, session=None, 
                 prefer_async=False):
        # ...
        self._prefer_async = prefer_async

    def search(self, query, *, language="ADQL", maxrec=None, uploads=None, 
               force_sync=False, **keywords):
        if self._prefer_async and not force_sync and self._supports_async():
            return self.run_async(query, language=language, maxrec=maxrec, uploads=uploads, **keywords)
        else:
            return self.run_sync(query, language=language, maxrec=maxrec, uploads=uploads, **keywords)

The benefits here is that users will get the exact same behavour (zero-risk) and it is an opt-in feature, while leaving the door open for a future change to the default behaviour.
Downside is probably that users need to know about the option to enable it so it may have slower adoption.

Both approaches would check the /capabilities to see whether the service supports async:

Usage Examples

Approach 1: Automatic async-first

service = TAPService("http://example.com/tap")
results = service.search("SELECT * FROM table")  # Uses async if available

# Can still force sync when needed
results = service.search("SELECT * FROM table", force_sync=True)

Approach 2: Opt-in parameter

# Default behavior (unchanged)
service = TAPService("http://example.com/tap")
results = service.search("SELECT * FROM table")  # Always sync

# Opt-in to async-prefer behavior
service = TAPService("http://example.com/tap", prefer_async=True)
results = service.search("SELECT * FROM table")  # Uses async if available

# Can still force sync
results = service.search("SELECT * FROM table", force_sync=True)

Any thoughts on this? If it makes sense I'm happy to work on a PR to enable it.

[msdemlei]

On Wed, Jun 25, 2025 at 01:30:57PM -0700, stvoutsin wrote: Currently `TAPService.search()` is just an alias to `run_sync()`, which means that all queries use sync execution regardless of service capabilities. I think for many/most service providers this may not be the optimal choice, and at least in our case we'd prefer if search uses run_async.

For most services, sync is much faster (it certainly is for DaCHS), and for small queries, it is absolutely adequate. Also note that the TAP standard *requires* both sync and async, so saying "prefer async" would mean "run async everywhere"; and our current TAP registry scheme (regrettably, see http://ivoa.net/documents/caproles/) doesn't allow clients to discover the presence of async anyway. Finally, as someone who has been running all-VO async queries occasionally, let me confess that several async implementations out there are severely substandard (i.e., are broken so badly that they don't interoperate with pyvo), whereas the sync endpoints are halfway ok. In sum, I'd be reluctant to change the default. It's likely we'd be breaking or downgrading quite a bit of code that's out there. Having said that:

service = TAPService("http://example.com/tap", prefer_async=True) results = service.search("SELECT * FROM table") # Uses async if available

That sounds reasonable and doesn't even need to unconditionally pull the capabilities (as I said, async must be there anyway). Since it's such a small amount of code, I'd say we should just do it if it helps your use case. However, if you say that data providers may prefer async as a matter of policy... perhaps we should let them say that. The natural place for that would be in TAPRegExt, and I'd be happy to prototype some text in there, and you could do the server-side reference implemenation; I'm sure we could convince the other pyVO maintainers that pyVO could be the client-side reference implementation. What do you think?

[bsipocz]

In astroquery I do call run_async directly when the user asks for async in the wrapper convenience function rather than trying to guess, so we may just need to document it more?
I mean if your service prefers it, use it in the examples rather than of the search alias.

(Fwiw I really dislike the search() anyway, and would prefer if we required to be explicit all the time, but I suppose that ship has long sailed before I became a maintainer here)

[stvoutsin]

In astroquery I do call run_async directly when the user asks for async in the wrapper convenience function rather than trying to guess, so we may just need to document it more? I mean if your service prefers it, use it in the examples rather than of the search alias.

(Fwiw I really dislike the search() anyway, and would prefer if we required to be explicit all the time, but I suppose that ship has long sailed before I became a maintainer here)

Indeed in our user documentation we advertise async either explicitly or through run_async although we still get users who run search() because they've seen that in doc examples elsewhere.

[stvoutsin]

On Wed, Jun 25, 2025 at 01:30:57PM -0700, stvoutsin wrote:
Currently TAPService.search() is just an alias to run_sync(),
which means that all queries use sync execution regardless of
service capabilities.
I think for many/most service providers this may not be the optimal
choice, and at least in our case we'd prefer if search uses
run_async.
For most services, sync is much faster (it certainly is for DaCHS),
and for small queries, it is absolutely adequate.

Also note that the TAP standard requires both sync and async, so
saying "prefer async" would mean "run async everywhere"; and our
current TAP registry scheme (regrettably, see
http://ivoa.net/documents/caproles/) doesn't allow clients to
discover the presence of async anyway.

Finally, as someone who has been running all-VO async queries
occasionally, let me confess that several async implementations out
there are severely substandard (i.e., are broken so badly that they
don't interoperate with pyvo), whereas the sync endpoints are halfway
ok.

In sum, I'd be reluctant to change the default. It's likely we'd be
breaking or downgrading quite a bit of code that's out there.

Having said that:
service = TAPService("http://example.com/tap", prefer_async=True)
results = service.search("SELECT * FROM table") # Uses async if available
That sounds reasonable and doesn't even need to unconditionally pull
the capabilities (as I said, async must be there anyway). Since it's
such a small amount of code, I'd say we should just do it if it helps
your use case.

However, if you say that data providers may prefer async as a matter
of policy... perhaps we should let them say that. The natural place
for that would be in TAPRegExt, and I'd be happy to prototype some
text in there, and you could do the server-side reference
implemenation; I'm sure we could convince the other pyVO maintainers
that pyVO could be the client-side reference implementation.

What do you think?

I'd be happy if we go with approach 2) for now and I can PR the fix.
I do also like the idea that a data provider can advertise that clients should prefer async as a policy, so if this is something that we can work towards in TAPRegExt (with a follow-up fix in the clients to honor the preference), this would pretty much do what we need. We're happy to work on the server-side implementation for this.

[msdemlei]

On Thu, Jun 26, 2025 at 10:18:08AM -0700, stvoutsin wrote: I do also like the idea that a data provider can advertise that clients should prefer async as a policy, so if this is something that we can work towards in TAPRegExt (with a follow-up fix in the clients to honor the preference), this would pretty much do what we need. We're happy to work on the server-side implementation for this.

Ok... let's brainstorm here for a moment how that should happen. (a) I think the most straightforward way would be to introduce a dedicated element <preferredMode>async</preferredMode> This could then also be sync; what the semantics would be if the element is missing (no preference? sync preference?) I'm not sure. This arguably is a bit on the fat side. I've been wondering whether we could do something "light" on the interface element. vs:ParamHTTP has, for instance, a queryType, and we could, as a matter of convention, say if it's POST, that's a hint to clients they should do async. Yuck. And that's the least hacky trick I've come up with what we have in vs:ParamHTTP. (b) A fairly fundamental way of changing things would be to put the various limits into groups. That's something we perhaps should have done from the start because for many services, limits on sync and async are fairly different. So, we could say <limits mode="sync-open"> <executionDuration> <default>10</default> </executionDuration> <outputLimit> <default>1000</default> <hard>20000</hard> </outputLimit> </limits> <limits mode="async-open"> <executionDuration> <default>10000</default> </executionDuration> <outputLimit> <default>100000</default> <hard>20000000</hard> </outputLimit> </limits> Other modes would be sync-auth and async-auth. This would solve quite a few other use cases, but that's clearly a major change (though it wouldn't be breaking if we kept the "root" limits as "typical" or "worst case"). (c) Similarly fundamental, but a lot lighter, would be something that's been on my mind for a long time: nudge VOResource towards RDF a bit. In this case, I'd say that would be by introducing a hint element. For your use case, you'd write <hint property="vor:preferredMode">async</hint> More generally, hint (or similar elements that would communicate RDF triples) should be able to take a subject, too. And it's there where it becomes complicated, because doing this RDF container in a way that keeps the VO Registry content halfway predictable will be hard. Do you have thoughts about that? Now that I've written all this, I think I could go to DAL+Registry with it, too; but then if you want something quickly, I think just implementing (a) and finally pushing for TAPRegExt 1.1, perhaps introducing the RDF containers with the hypothetical DALIInterface later, would be the safest way forward.

[stvoutsin]

Some thoughts on this, but take them with a grain of salt because I'm not well read on registry matters:

In terms of using vs:ParamHTTP queryType approach, I think agree with that one probably not being the best approach - correlating HTTP method to execution mode would be confusing for clients and limiting for providers. Services might legitimately want to use POST for sync operations for example.

Regarding approach (c), while I haven't fully explored the RDF hints concept, I can see it provides maximum flexibility but I'm seeing the potential for complexity mainly from the client's point of view but also registry. Vocabulary management will probably get complicated, similarly validation and the client implementation side seems complex (looping through hints to find the right execution mode property), but I may be easily convinced with examples of what this may look like.

I'm wondering if a middle ground/hybrid approach where RDF hints handle semantic/discovery concerns while operational service metadata remains structured would be reasonable?

Approach (a) does feel somewhat like a bandaid, but maybe it wins on simplicity and backward compatibility.

Approach (b) does indeed address the gap of advertising different different limits per execution mode.

If this was chosen could we define the mode preference as an attribute of the limit?

<limits preferred="true" mode="async-open">

That does feel semantically strange however since we're saying here is my preferred limit (?).

Perhaps a combination of (a) and (b) might work best: use a simple element for clear preference communication, while adding grouped limits to fix the underlying architecture.

One question I have on this what is the enumeration for preferredMode.

If I want to advertise that clients should use:

The async interface, or
The async + auth interface specifically, or
Any authenticated interface regardless of sync/async

Should the schema define an enumeration like: sync | async | sync-open | async-auth | sync-auth | sync-open | authenticated? Or keep it simple with just sync | async and handle authentication preferences separately?