MaxCompute:Java UDFs

Sample code

The following examples implement a Lower UDF that converts a string to lowercase.

Using Java data types:

// Package: org.alidata.odps.udf.examples
package org.alidata.odps.udf.examples;
// Inherit the UDF base class
import com.aliyun.odps.udf.UDF;

public final class Lower extends UDF {
    // evaluate defines the SQL signature: (String) -> String
    public String evaluate(String s) {
        if (s == null) {
            return null;
        }
        return s.toLowerCase();
    }
}

Using Java writable data types:

// Package: com.aliyun.odps.udf.example
package com.aliyun.odps.udf.example;
import com.aliyun.odps.io.Text;   // Writable type for STRING
import com.aliyun.odps.udf.UDF;

public class MyConcat extends UDF {
    private Text ret = new Text();

    // evaluate defines the SQL signature: (Text, Text) -> Text
    public Text evaluate(Text a, Text b) {
        if (a == null || b == null) {
            return null;
        }
        ret.clear();
        ret.append(a.getBytes(), 0, a.getLength());
        ret.append(b.getBytes(), 0, b.getLength());
        return ret;
    }
}

MaxCompute also supports Hive UDFs whose Hive version is compatible with MaxCompute. For details, see Hive UDF compatibility.

Duplicate class names across JAR files

JAR files for different UDFs must not contain classes with the same fully qualified name but different logic. For example, if udf1.jar and udf2.jar both contain com.aliyun.UserFunction.class with different implementations, calling both UDFs in the same SQL statement causes MaxCompute to load only one version — resulting in unexpected behavior or a compilation error.

Object types, not primitives

The input parameters and return value of an evaluate method must use Java object types (e.g., String, Long, Integer). Primitive types such as int or boolean are not supported.

NULL handling

MaxCompute SQL NULL values map to Java null. Because Java primitive types (int, boolean, float, etc.) cannot hold null, using them in an evaluate signature causes type errors at runtime. Always use the boxed object equivalents (Integer, Boolean, Float, etc.), and explicitly check for null before processing.

// Correct: uses String (object type), handles null
public String evaluate(String s) {
    if (s == null) {
        return null;
    }
    return s.toLowerCase();
}

// Wrong: uses primitive int — cannot represent SQL NULL
// public int evaluate(int n) { ... }

Internet access

MaxCompute does not allow UDFs to access the Internet by default. To enable Internet access, fill in the network connection application form based on your business requirements and submit it. After approval, the MaxCompute technical support team will help you establish the connection. For details, see network connection application formNetwork connection process.

VPC access

MaxCompute does not allow UDFs to access resources in virtual private clouds (VPCs) by default. To access VPC resources from a UDF, establish a network connection between MaxCompute and the VPC. For details, see Use UDFs to access resources in VPCs.

Table read restrictions

UDFs, user-defined aggregate functions (UDAFs), and user-defined table-valued functions (UDTFs) cannot read data from the following table types:

• Tables on which schema evolution is performed

• Tables that contain complex data types

• Tables that contain JSON data types

• Transactional tables

Use MaxCompute Studio

This example creates a Lower UDF that converts strings to lowercase.

Step 1: Prepare your environment

Install MaxCompute Studio and connect it to your MaxCompute project:

1. Install MaxCompute Studio

2. Connect to a MaxCompute project

3. Create a MaxCompute Java module

Step 2: Write UDF code

1. In the Project tab, navigate to src > main > java, right-click java, and choose New > MaxCompute Java.

   

2. In the Create new MaxCompute java class dialog box, click UDF, enter a class name in the Name field, and press Enter. Enter the name in PackageName.ClassName format. The system creates the package automatically. This example uses the class name Lower.

   

3. Write your UDF code in the editor.

   To debug the UDF locally before uploading, see Develop and debug UDFs.

   package com.aliyun.odps.udf.example;
   import com.aliyun.odps.udf.UDF;
   
   public final class Lower extends UDF {
       public String evaluate(String s) {
           if (s == null) {
               return null;
           }
           return s.toLowerCase();
       }
   }

   

Step 3: Upload the JAR file and register the UDF

Right-click the JAR file and select Deploy to server.... In the Package a jar, submit resource and register function dialog box, configure the following parameters and click OK.

Step 4: Debug the UDF

In the left-side navigation pane, click the Project Explore tab. Right-click your MaxCompute project, select Open Console, and run:

select lower_test('ABC');

Expected output:

+-----+
| _c0 |
+-----+
| abc |
+-----+

Use DataWorks

Step 1: Prepare your environment

Activate DataWorks and associate a DataWorks workspace with your MaxCompute project. For details, see DataWorks.

Step 2: Write UDF code

Write your UDF in a Java development tool and package it as a JAR file. Sample code:

package com.aliyun.odps.udf.example;
import com.aliyun.odps.udf.UDF;

public final class Lower extends UDF {
    public String evaluate(String s) {
        if (s == null) {
            return null;
        }
        return s.toLowerCase();
    }
}

Step 3: Upload the JAR file and register the UDF

Upload the JAR file and register the UDF in the DataWorks console:

1. Create and use MaxCompute resources

2. Create and use a MaxCompute function

Step 4: Debug the UDF

Create an ODPS SQL node in the DataWorks console and run the following SQL statement to verify the UDF. For details on creating an ODPS SQL node, see Create an ODPS SQL node.

select lower_test('ABC');

Expected output:

+-----+
| _c0 |
+-----+
| abc |
+-----+

Use the MaxCompute client (odpscmd)

Step 1: Prepare your environment

Download the MaxCompute client installation package from GitHub, install the client, and configure the config file to connect to your MaxCompute project. For details, see MaxCompute client (odpscmd).

Step 2: Write UDF code

Write your UDF in a Java development tool and package it as a JAR file. Sample code:

package com.aliyun.odps.udf.example;
import com.aliyun.odps.udf.UDF;

public final class Lower extends UDF {
    public String evaluate(String s) {
        if (s == null) {
            return null;
        }
        return s.toLowerCase();
    }
}

Step 3: Upload the JAR file and register the UDF

Run the following commands in odpscmd:

1. Upload the JAR file as a resource — see ADD JAR.

2. Register the UDF — see CREATE FUNCTION.

Step 4: Debug the UDF

Run the following SQL statement to verify the UDF:

select lower_test('ABC');

Expected output:

+-----+
| _c0 |
+-----+
| abc |
+-----+