jameslamb opened a new pull request, #41892: URL: https://github.com/apache/spark/pull/41892
### What changes were proposed in this pull request? Proposes a slight modification to the docs for SQL function `array_position()`, to clarify the return value and that function's behavior when no match is found. ### Why are the changes needed? In my opinion, the docs at https://spark.apache.org/docs/latest/api/sql/index.html#array_position leave too much room for confusion. > *array_position(array, element) - Returns the (1-based) index of the first element of the array as long.* > Examples: > ``` > SELECT array_position(array(3, 2, 1), 1); > 3 > ``` Because the return value also happens to be a return value in the example array, and because the doc says "first element" instead of "first matching element", I think it'd be easy to misunderstand this function as doing something like "given `array_position(a, i)`, return `arr[i]`". The code comment on this function is very clear, but I think the user-facing docs would benefit from similar clarification: https://github.com/apache/spark/blob/05bc73a83921a9e606609a12750932f95bd5b3f8/sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/collectionOperations.scala#L2134-L2141 This PR proposes modifying the doc to remove such confusion, by: * providing an example array and search values which are unlikely to be confused with indices * modifying the example such that it shows the behavior when `array_position(a, v)` is called on an array `a` containing multiple instances of `v` * adding an example showing the behavior of this function when no match is found ### Does this PR introduce _any_ user-facing change? Yes, minor user-facing documentation change. ### How was this patch tested? I did not test this patch at all, just followed the patterns I saw elsewhere in the same file for documentation strings. I did check that this was the only place this text came from, like this: ```shell git grep 'index of the first element of the array as long' ``` ### Notes for Reviewers Thanks very much for your time and consideration. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
