You can download all code samples from here. If you already have my Power Query editor for Notepad++ (or want to build it) you can open the file in Notepad++. Otherwise open it in a simple text editor and paste it into the Advanced Editor of Power Query or Power BI Desktop. I will refer more frequently to the Microsoft Power Query for Excel Formula Language Specification. You can download it here.

Extend the functionality – sort the list in ascending or descending order

Now I would like to extend the funtionality of my custom function in that way, that the user can choose, wether the returned list of dates will be sorted in an ascending or descending order. Therefore I do the following steps:

• I add the optional parameter SO (short for sort order).
• I also change the functions‘ code, so that the list will be sorted in ascending order, if SO is null, or „ascending“. If it is something different, the sort order will be descending.
• I add SO also to the definition of my custom type fnType

All these changes are highligted in red in the following screenshot:

The result is the following:

With this additional parameter I am now able to sort the date list in ascending or descending order by typing the words „descending“ or „ascending“ into the text box. A much better user experience would of course be if this were not a free field, but sorting could be selected via a dropdown. Let’s do this in the next step.

Limiting parameters to Allowed Values

Passing values of parameters as free text can often lead to errors. It would be better to use a dropdown, which lets you select the allowed contents of the parameters. This can be achieved via Documentation.AllowedValues as part of the metadata record of the specific parameter.

What has a been a usual textbox before, now is a dropdown, with only the allowed values (and an empty value) to choose for the user.

These allowed values are static. They won’t change over time. But what if I need the allowed values to be dynamical?

Dynamically control Allowed Values of the parameters

Now let’s say I want to dynamically set the values to choose. What if I want the user to be able to choose only date values from the future?

What I do in the above script is the following:

• I define the variable Tomorrow as todays date (DateTime.Date(DateTime.LocalNow())) plus 1 day ( + #duration(1,0,0,0))
• In addition I define the allowed values for both, date1 and date2 as a dynamic list of 100 dates, starting from tomorrow, by using List.Dates(Tomorrow, 100, #duration(1,0,0,0))

The resulting documentation looks like this:

As you can see in the screenshot above, the parameter date1 (and also date2, even it is not visible on the screenshot) got a different user interface. While I had a small calendar icon first, to choose a specific date, I now have a dropdown list with only the allowed values in it. See the difference here:

Adding more valuable information to the function parameters

In addition to Documentation.AllowedValues, there is some other information that can be added to the documentation of a custom functions parameters. Those are the following:

• Documentation.FieldCaption:
• Documentation.FieldDescription
• Documentation.SampleValues

The following script uses the above mentioned fields within the metadata record:

The expectation is that these added fields in the metadata record will lead to more information in the documentation. However, a look at the documentation shows that this is unfortunately not the case:

Hmm, that wasn’t what I expected. I have only found one way to make the parameter documentation visible anyway: By removing the documentation of the function (not the parameter), which is the red marked part in the following screenshot:

By removing all the red marked part of the M script, the documentation for the parameters becomes visible (but of course the documentation of the function disappears):

For me it looks as if I always have to choose between the documentation of my function or the documentation of my function parameters. Both at the same time seems to be impossible, which of course makes little sense. But just because I couldn’t do it doesn’t mean that it can’t be done. If anyone out there has an idea of how it works, please say

My thanks go to the authors of the following excellent contributions on this topic: Chris Webb, Matt Masson, Imke Feldmann:

• https://github.com/Microsoft/DataConnectors/blob/master/docs/function-docs.md
• https://blog.crossjoin.co.uk/2014/11/27/specifying-allowed-values-sample-values-and-descriptions-for-function-parameters-in-power-querypart-1
• https://blog.crossjoin.co.uk/2014/12/02/specifying-allowed-values-sample-values-and-descriptions-for-function-parameters-in-power-querypart-2
• http://www.thebiccountant.com/2017/05/11/how-to-edit-m-function-metadata/

Regards from Germany,

Lars

I write my posts for you, the reader. Please take a minute to help me write my posts as well as possible. Thank you

[yasr_visitor_multiset setid=2]

Lars Schreiber

Lars ist Berater, Entwickler und Trainer für Microsoft Power BI. Er ist zertifizierter Power BI-Experte und Microsoft Trainer. Für sein Engagement in der internationalen Community wurde Lars seit 2017 jährlich durch Microsoft der MVP-Award verliehen. Lies hier mehr…

ssbi-blog.de

Der Beitrag Writing documentation for custom M-functions, Part3 erschien zuerst auf THE SELF-SERVICE-BI BLOG.

You can download all code samples from here. If you already have my Power Query editor for Notepad++ (or want to build it) you can open the file in Notepad++. Otherwise open it in a simple text editor and paste it into the Advanced Editor of Power Query or Power BI Desktop. I will refer more frequently to the Microsoft Power Query for Excel Formula Language Specification. You can read it here.

Defining and adding metadata to the custom function – Version 2

In my previous post I defined a record, which then functioned as my metadata record. Then I changed the type of my custom function and in this step I added the new metadata record to my custom function. In this Version 2, which I prefer over Version 1,  I will explicitly define a new type function with its associated metadata record. This gives me greater flexibility to access the individual parameters of the function. This will be part of the third part of this series in a couple of weeks.

Metadata definition

This time, the definition of the metadata record doesn’t look different to Version 1, but I do not only define a metadata record, but a complete new type value. Take a look at the following screenshot:

What you can see is:

1. The definition of a new type value fnType of type function. This type value contains all the parameters of my custom function, with their specific data types (date) and the data type of the function’s return value (list). Behind the definition of the type value you see the key word meta, which introduces the definition of the metadata record
2. This is the definition of the metadata record, as you already know it from my previous post.

You might think: „And why is this his prefered version of adding documentation to a custom function? This looks much more difficult!“ This may be true, but this version allows me to modify the metadata not only for the custom function, but also for each parameter of the custom function. How this works and what it can be useful for, you will find out in the next post If you want to dig deeper into the M type value system, take a look into the Microsoft Power Query for Excel Formula Language Specification, chapter 5 (Types). Now let’s add this type to my custom functon.

Adding metadata to the function

Adding this type (including the documentation) to my custom function is pretty easy:

At the end of the script I simply replace the type of my function fn by the newly created type fnType, using the function Value.ReplaceType(). The result is the same, compared to my previous post:

My next post will cover how you can document single parameters and also define allowed values. At this point using version 2 brings real added value.

Regards from Germany,

Lars

I write my posts for you, the reader. Please take a minute to help me write my posts as well as possible. Thank you

[yasr_visitor_multiset setid=2]

Lars Schreiber

Lars ist Berater, Entwickler und Trainer für Microsoft Power BI. Er ist zertifizierter Power BI-Experte und Microsoft Trainer. Für sein Engagement in der internationalen Community wurde Lars seit 2017 jährlich durch Microsoft der MVP-Award verliehen. Lies hier mehr…

ssbi-blog.de

Der Beitrag Writing documentation for custom M-functions, Part2 erschien zuerst auf THE SELF-SERVICE-BI BLOG.

You can download all code samples from here. If you already have my Power Query editor for Notepad++ (or want to build it) you can open the file in Notepad++. Otherwise open it in a simple text editor and paste it into the Advanced Editor of Power Query or Power BI Desktop. I will refer more frequently to the Microsoft Power Query for Excel Formula Language Specification. You can download it here.

What is a documentation and why do I need one?

If you have already written your own custom functions in M, you surely know the value of a well-documented function. If not, take a look at the documentation of List.Sum():

By typing = List.Sum into the formula bar of a Power Query query you get the official documentation of this native M function. This documentation can provide the following information:

• Name of the function
• function description
• the function parameters, including their names, data types and if they are optional or not
• the syntax of the function and the data type of the returned value
• an example on how to use the function

This information about the function structure and its use makes it much easier for the user to find the right one with currently more than 630 functions. It would therefore be very useful to be able to add such a documentation to a custom function. I’ll show you how to do that.

My tiny custom M function

The following custom function is the one to be documented in this post:

This function does the following: The function takes the two parameters date1 and date2 (both of type date) and creates a list of date values, starting with date1, up to and including date2.

I would like to add documentation for this function so that other users can use it more easily. This can also be very helpful for myself if I have written a lot of own functions. To add documentation to this function, I need to modify the metadata of the function. That’s why I would like to take a brief look at the subject of metadata.

Metadata

Metadata is additional data for a specific value, stored in a so called metadata record. Metadata is a large subject area and requires its own post (which I will write in near future). You can find an introduction to this topic under point 1.7 in the Power Query Formula Language Specification. Nevertheless, I would like to briefly discuss some of the key features here.

Metadata in general

As already mentioned, metadata is additional information that can be assigned to values (records, tables, etc.). These are stored in a single record. If no metadata is stored, the metadata record is empty. The stored metadata can be accessed with the function Value.Metadata(). An example certainly makes this more vivid:

This example shows the following steps:

1. The initial situation: The base table with column Row, which contains the row numbers and column Values, which contains sample values.
2. In this step I create a new column that contains the values, but also the row number that is stored within the metadata, by using the key word meta, followed by the metadata record.
3. I delete the column Row, so that only the column Value + Metadata remains.
4. I use the formula Value.Metadata([#"Value + Metadata"])[Row]to retrieve the row number information from the metadata.

The functions metadata

You can add pretty much anything you want to the metadata of your function, but there are some pretty interesting key words, that you should know. These key words will be displayed by Power Query in the function documentation and they are the following:

• Documentation.Name
• Documentation.LongDescription
• Documentation.Description
• Documentation.Examples

Keep that in mind: If you define Documentation.Description and Documentation.LongDescription, there will only be shown the LongDescription.

There are two versions of defining and adding metadata to a custom function, that I know about. I will start with the more common one.

Defining and adding metadata to the custom function – Version 1

If you search in forums or read blogs on this topic, you will most likely come across this version. I show them for the sake of completeness, because I prefer version number 2.

Metadata definition

As I mentioned before, metadata is stored in a record, so we have to define a record.

This record has the following fields:

• Documentation.Name of type text,
• Documentation.Description of type text,
• Documentation.Example of type list. Type list is necessary, because you can save more than one example. This list is a list of records and the record’s fields are:
  • Description of type text; usually stores the same information as Documentation.Description;
  • Code of type text; here you can show how the usage of the function looks like;
  • Result of type text; Here you can show how an example return value of the function could look like.

My next task is to add this metadata to the function.

Adding metadata to the function

Now, that I have defined the metadata for my custom function, I want to add them to the function.

Therefore I do the following steps:

1. I wrap my original function in a further let-expression. Why do I do that? This gets important in step 3, where I want to overwrite the functions metadata. Therefore I need „access“ to the function itself. A characteristic feature of let-expression is that after that in all variables can be accessed, that are located between the let and the in. For detailed information about this behaviour, please read the following series of post, regarding the Environment concept in M.
2. In this step I put in the metadata, which I already defined in my metadata record Documentation_Metadata. I removed the complete definition from this screenshot, to make it less complex. You will see the complete code at the end of this post.
3. This step overwrites the metadata of my custom function fn with the newly defined metadata record Documentation_Metadata. Let us consider the function from the inside out.
   • Value.Type(fn)returns function, because the type of the custom function fn is function.
   • Value.ReplaceMetadata()replaces the input’s metadata information. The input is function and I replace the metadata of this type by my record Documentation_Metadata. The result is a type function with a new metadata record. This is important for the next step.
   • Value.ReplaceType()takes the function fn as first parameter and replaces the old type function with the new type function, which now has the metadata record inside.

Now that I have completed all the necessary steps, let’s take a look at the final result for this post.

The final result

I have taken all these steps to ensure that my custom function is adequately documented both for myself and for third parties. The following screenshot shows the result of my work and the transition from source code to help texts in Power Query.

In my next post I will show the version 2, my preferred variant to add a documentation to my custom functions.

Regards from Germany,

Lars

I write my posts for you, the reader. Please take a minute to help me write my posts as well as possible. Thank you

[yasr_visitor_multiset setid=2]

Lars Schreiber

Lars ist Berater, Entwickler und Trainer für Microsoft Power BI. Er ist zertifizierter Power BI-Experte und Microsoft Trainer. Für sein Engagement in der internationalen Community wurde Lars seit 2017 jährlich durch Microsoft der MVP-Award verliehen. Lies hier mehr…

ssbi-blog.de

Der Beitrag Writing documentation for custom M-functions, Part1 erschien zuerst auf THE SELF-SERVICE-BI BLOG.