docs: move TopK user defined operator example into extending-operators guide

[sjhddh]

Which issue does this PR close?

• Closes Move code in user_defined_plan.rs to the extending-operators doc #15774.

Rationale for this change

The extending-operators user guide only documented the µWheel optimizer at a high level. The full worked example of building a custom operator lived in datafusion/core/tests/user_defined/user_defined_plan.rs, whose own module header noted the code "is better to put ... in examples". #15774 asks to move that example into the user guide, using custom-table-providers.md as the format reference.

What changes are included in this PR?

• Expand docs/source/library-user-guide/extending-operators.md with a complete TopK walkthrough:
  • the problem and the naive Sort + Limit plan it improves on,
  • the logical node (UserDefinedLogicalNodeCore),
  • the OptimizerRule that rewrites Limit + Sort into the node,
  • the physical operator (ExecutionPlan) and its streaming reader,
  • the ExtensionPlanner / QueryPlanner wiring, and
  • how to register everything on a SessionState and run a query.
• Trim the now-redundant narrative from the user_defined_plan.rs header so the guide is the single source of the walkthrough; the header now links to the guide.

This addresses the two follow-ups alamb raised on #15832:

1. Remove the redundant example. The explanatory walkthrough is removed from the test and now lives only in the guide.
2. Add more detail. Each component has prose explaining what the trait methods are for, not just the code.

On the first point: I kept the implementation in user_defined_plan.rs rather than deleting the file, because the module has grown to also test user defined plan invariants (InvariantMock, the topk_invariants* tests). Those tests are not documentation and would be lost on a full delete. Happy to move them elsewhere or delete more aggressively if you'd prefer.

Following custom-table-providers.md, the code blocks use rust,ignore: they reference the surrounding types and a test-only schema, so they are illustrative rather than standalone-compilable.

Are these changes tested?

The migrated code is the existing, tested TopK implementation; cargo test --test user_defined_integration -p datafusion topk still passes (4 tests, including the invariant tests). The guide is rendered docs only.

Are there any user-facing changes?

Documentation only. No API changes.

[alamb]

On the first point: I kept the implementation in user_defined_plan.rs rather than deleting the file, because the module has grown to also test user defined plan invariants (InvariantMock, the topk_invariants* tests). Those tests are not documentation and would be lost on a full delete. Happy to move them elsewhere or delete more aggressively if you'd prefer.

Would you be willing to move them, as a follow on PR, to unit tests (if they aren't already covered)? I agree that piggy backing invariant tests in other examples makes them harder to follow

[alamb]

Thnk you @sjhddh -- I kicked off the tests and left some comments about how to frame the example. Let me know what you think

[alamb]

This is out of date as DataFusion now has a special TopK mode in its sort operator. I recommend we just point this out and then move on with the example

> EXPLAIN SELECT customer_id, revenue FROM sales ORDER BY revenue DESC LIMIT 3;
+---------------+-------------------------------+
| plan_type     | plan                          |
+---------------+-------------------------------+
| physical_plan | ┌───────────────────────────┐ |
|               | │       SortExec(TopK)      │ |
|               | │    --------------------   │ |
|               | │          limit: 3         │ |
|               | │                           │ |
|               | │       revenue@1 DESC      │ |
|               | └─────────────┬─────────────┘ |
|               | ┌─────────────┴─────────────┐ |
|               | │         EmptyExec         │ |
|               | └───────────────────────────┘ |
|               |                               |
+---------------+-------------------------------+
1 row(s) fetched.
Elapsed 0.020 seconds.

> EXPLAIN FORMAT INDENT SELECT customer_id, revenue FROM sales ORDER BY revenue DESC LIMIT 3;
+---------------+-------------------------------------------------------------------------------+
| plan_type     | plan                                                                          |
+---------------+-------------------------------------------------------------------------------+
| logical_plan  | Sort: sales.revenue DESC NULLS FIRST, fetch=3                                 |
|               |   TableScan: sales projection=[customer_id, revenue]                          |
| physical_plan | SortExec: TopK(fetch=3), expr=[revenue@1 DESC], preserve_partitioning=[false] |
|               |   EmptyExec                                                                   |
|               |                                                                               |
+---------------+-------------------------------------------------------------------------------+
2 row(s) fetched.
Elapsed 0.004 seconds.

[alamb]

I think we should also note that DataFusion has a much more sophisticated topk implementation built in, but this is just for an example

Maybe we can update the example so it disables the limit pushdown optimizer pass 🤔

Suggested change

	Out of the box, DataFusion plans this as a `Sort` feeding a `Limit`:
	Out of the box, DataFusion already contains an optimized TopK implementation and our example here
	is just for demonstration purposes. If we disable the LimitPushdown optimization, we see the original plan is a `Sort` feeding a `Limit`:

[alamb]

it woudl be great here to update the example to use assert_batches_eq! so that the actual output is captured in the example too

[sjhddh]

Thanks for the review @alamb! Pushed an update:

1. Reframed the intro to point out that DataFusion already ships an optimized TopK and that this operator is just for demonstration. Took your suggested wording verbatim. The Sort -> Limit EXPLAIN below it is now described as the original plan you get with LimitPushdown disabled, rather than the default. I left it as an illustrative block since there isn't a clean SQL knob to disable a single logical rule mid-session - happy to wire the example up to actually drop the pass from the optimizer if you'd prefer that over the prose note.

2. Swapped df.show() for assert_batches_eq! in the "Putting It Together" block so the expected output is captured inline. Rows are taken from the runnable user_defined_plan.rs test.

On the follow-on: agreed the invariant tests piggybacking on the example hurts readability. I'll move InvariantMock / the topk_invariants* tests into proper unit tests in a separate PR so this one stays focused on the docs example.